Skip to main content
EntityLocker enables organizations to securely share verified business documents like incorporation certificates, GST registrations, and licenses with your application through user consent. This recipe walks you through:
  • Initiating an EntityLocker consent session
  • Tracking consent completion
  • Downloading consented documents
  • Fetching user and entity verification details
Before you begin, ensure you have:
  • Generated a Sandbox x-api-key
  • Obtained a JWT authorization token using the Authenticate API
  • A business entity ready to provide consent through EntityLocker
1

Initiate EntityLocker session

Use the Initiate Session API to start the EntityLocker consent flow.The API returns a session_id to track the session and an authorization_url where you must redirect the user to authenticate and grant document consent.

Request

curl --request POST \
  --url https://api.sandbox.co.in/kyc/entitylocker/sessions/init \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --data '{
  "@entity": "in.co.sandbox.kyc.entitylocker.session.request",
  "flow": "signin",
  "redirect_url": "https://yourdomain.com/callback"
}'

{
  "code": 200,
  "timestamp": 1765534184274,
  "data": {
    "@entity": "in.co.sandbox.kyc.entitylocker.session.response",
    "session_id": "d3f8897e-f1ff-4449-9704-7073f6930296",
    "authorization_url": "https://entity.digilocker.gov.in/public/oauth2/1/authorize?response_type=code&client_id=..."
  },
  "transaction_id": "02683ff9-2abc-42ab-a050-945f21068bce"
}
​
session_id
string
required
Unique identifier to track this EntityLocker consent session
​
authorization_url
string
required
Redirect URL where the user authenticates and grants consent for document sharing
After receiving the response, redirect the user to the authorization_url to complete authentication and consent.
Do not proceed to fetch documents until the user completes the EntityLocker consent flow and the session status is succeeded.
2

Check session status

After the user completes the consent flow, verify the session status using the Get Session Status API.

Request

curl --request GET \
  --url https://api.sandbox.co.in/kyc/entitylocker/sessions/{session_id}/status \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'x-api-key: <your-api-key>'

{
  "code": 200,
  "timestamp": 1752580258171,
  "data": {
    "id": "839fd8a0-d645-42e1-a904-bb43353b0139",
    "created_at": 1752579445983,
    "@entity": "in.co.sandbox.kyc.entitylocker.session",
    "status": "created"
  },
  "transaction_id": "800ff751-2191-4b7d-b20a-8301790a3e19"
}

{
  "code": 200,
  "timestamp": 1751975475945,
  "data": {
    "id": "f1bd0342-cc1d-4051-8301-e8ee17e3a3c3",
    "created_at": 1751975341292,
    "updated_at": 1751975465494,
    "@entity": "in.co.sandbox.kyc.entitylocker.session",
    "status": "succeeded",
    "documents_consented": [
      "company_master_details",
      "gstn_details",
      "udhyam_certificate"
    ]
  },
  "transaction_id": "6daaaf0c-21f6-4e32-93b5-19ec4415d7fa"
}
Session statuses:
  • created – session initiated, user has not completed consent
  • succeeded – user authenticated successfully and granted document consent
  • failed – authentication or consent failed
  • expired – session expired before consent was granted
When the status is succeeded, the response includes documents_consented, listing the document types the entity approved for sharing.
Poll this endpoint periodically to check if consent is complete, or set up a webhook callback using the redirect_url parameter.
3

Fetch documents

Once the session status is succeeded, retrieve the consented documents using the Fetch Document API.EntityLocker returns all consented documents for the session as pre-signed download URLs. You don’t need individual document IDs.

Request

curl --request GET \
  --url https://api.sandbox.co.in/kyc/entitylocker/sessions/{session_id}/documents/{doc_type} \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'x-api-key: <your-api-key>'

{
  "code": 200,
  "timestamp": 1765781088023,
  "data": {
    "files": [
      {
        "@entity": "org.quicko.drive.file",
        "url": "https://in-co-sandbox-kyc-entitylocker-storage-dev.s3.ap-south-1.amazonaws.com/non-persistent/workspaces/...",
        "size": 108598,
        "metadata": {
          "ContentType": "application/pdf",
          "issuer_id": "in.gov.mca",
          "issuer": "Ministry of Corporate Affairs (MCA), Govt. of India",
          "LastModified": "19/12/2024",
          "description": "Company Master Details"
        }
      }
    ]
  },
  "transaction_id": "aa10bddf-1fc6-45a9-b0af-dc13613de60c"
}
Available document types:
  • company_master_details – incorporation certificate from Ministry of Corporate Affairs
  • gstn_details – GST registration certificate
  • udhyam_certificate – Udyam (MSME) registration certificate
Each file includes:
  • Pre-signed S3 url for direct download
  • File size in bytes
  • metadata including issuer, content type, and description
Document URLs are temporary and expire after a short duration (typically 1 hour). Download and store documents securely before they expire.
4

Fetch user profile

Retrieve details of the user who authenticated and granted consent on behalf of the entity using the Get User Profile API.

Request

curl --request GET \
  --url https://api.sandbox.co.in/kyc/entitylocker/sessions/{session_id}/user/profile \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'x-api-key: <your-api-key>'

{
  "code": 200,
  "timestamp": 1765889000461,
  "data": {
    "id": "96b14651-a333-547d-8de9-fee0be4f941e",
    "@entity": "in.co.sandbox.kyc.entitylocker.user.profile",
    "name": "Henil Rupesh Shah",
    "date_of_birth": "28/01/2002",
    "mobile": "9512120133",
    "gender": "male",
    "eaadhaar": true
  },
  "transaction_id": "7603165e-e591-4342-bb19-1d9f4caabb0f"
}
The response includes:
  • User’s full name
  • Date of birth
  • Mobile number
  • Gender
  • Whether they have an e-Aadhaar linked
Use this information for audit logs, identifying the authorized signatory, and compliance recordkeeping.
5

Fetch entity details

Retrieve verified entity-level information derived from the shared documents using the Get Entity Details API.

Request

curl --request GET \
  --url https://api.sandbox.co.in/kyc/entitylocker/sessions/{session_id}/entity \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'x-api-key: <your-api-key>'

{
  "code": 200,
  "timestamp": 1765888767565,
  "data": {
    "id": "4e8455e8-27db-50a0-99e9-0b0211a4811d",
    "@entity": "in.co.sandbox.kyc.entitylocker.entity",
    "name": "SANDBOX FINANCIAL TECHNOLOGIES PRIVATE LIMITED",
    "date_of_incorporation": "16/01/2023",
    "email": "help@sandbox.co.in",
    "mobile": "9099983246",
    "verified_by": "cin"
  },
  "transaction_id": "c4124d99-4854-446f-9b04-b8f8c12785d0"
}
The response includes:
  • Entity name (legal business name)
  • Date of incorporation
  • Contact email and mobile number
  • Verification source (e.g., CIN from MCA)
Use this verified entity information for:
  • Business KYC and onboarding
  • Compliance verification workflows
  • Internal audit trails
  • Downstream regulatory reporting

​
Next steps

With the fetched documents, entity details, and user profile information, you can:
  • Complete business onboarding and KYC verification
  • Store documents securely for compliance purposes
  • Validate entity information against other data sources
  • Trigger downstream workflows like account creation or credit assessment

View EntityLocker API reference

Explore detailed API documentation, parameters, and response schemas