Initialize DigiLocker Session

Endpoint Overview

POST /api/v1/digilocker/initialize

Description

This API endpoint initiates a DigiLocker integration session by generating an OAuth URL where end users can authenticate and authorize access to their DigiLocker documents. It's the first step in a multi-stage process that enables secure document retrieval from DigiLocker.

The generated URL directs users to a DigiLocker authentication page where they can log in and provide consent for document access. After successful authentication, users are redirected to your specified redirect URL, allowing for a seamless user experience.

Key Benefits

Streamlined document verification process without manual document uploads

Secure access to government-issued documents with user consent

Customizable session parameters including expiry time and user information prefill

Seamless integration with existing application flows through redirect URLs

Use Cases

Financial Services

Government Services

Healthcare

KYC verification during customer onboarding for banks and NBFCs

Loan application processing with instant document verification

Insurance policy issuance with validated identity documents

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication. Format: `Bearer {jwt_token}`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
data.prefill_options	Object	No	User information to prefill in the DigiLocker form
data.prefill_options.full_name	String	No	User's full name to prefill (max 250 characters)
data.prefill_options.mobile_number	String	No	User's mobile number to prefill
data.prefill_options.user_email	String	No	User's email address to prefill
data.signup_flow	Boolean	Yes	Set to true for new users (they must provide a PIN during registration). Set to false for existing DigiLocker users (proceeds with login).
data.auth_type	String	No	Authentication type: 'web' or 'app' (default: 'web')
data.verify_phone	Boolean	No	Whether to verify user's phone number (default: false)
data.verify_email	Boolean	No	Whether to verify user's email address (default: false)
data.allow_selection	Boolean	No	Allow document selection (readonly, default: false)
data.redirect_url	String	No	URL to redirect user after DigiLocker authentication
data.webhook_url	String	No	Webhook URL for callbacks
data.state	String	No	Custom state parameter for session tracking (max 100 characters)
data.local_frontend_url	String	No	Local frontend URL
data.aadhaar_xml	Boolean	No	Enable Aadhaar XML format (default: false)
data.send_sms	Boolean	No	Send SMS notifications (requires mobile_number, default: false)
data.send_email	Boolean	No	Send email notifications (requires user_email, default: false)
data.expiry_minutes	Integer	No	Session expiry time in minutes (default: 30, min: 5, max: 30)
data.voice_assistant	Boolean	No	Enable voice assistant (default: false)
data.voice_assistant_lang	String	No	Voice assistant language: 'hi', 'en', or 'both' (default: 'en')
data.retry_count	Integer	No	Number of retry attempts (default: 1, min: 1, max: 5)
data.skip_main_screen	Boolean	No	Skip main screen display (default: false)
data.logo_url	String	No	Custom logo URL

Example Request (Redirect URL)

{
  "data": {
    "signup_flow": true,
    "redirect_url": "https://google.com"
  }
}

Example Request (Webhook URL)

{
  "data": {
    "signup_flow": true,
    "redirect_url": "https://google.com",
    "webhook_url": "https://webhook.site/a6f4fcec-5ac8-4c82-96ea-7eded59fd59a"
  }
}

Process Response

API Response Parameters

Parameter	Type	Description
data.client_id	String	Unique identifier for the DigiLocker session
data.token	String	Authentication token for the session
data.url	String	DigiLocker OAuth URL where the user should be redirected
data.expiry_seconds	Integer	Session expiry time in seconds
status_code	Integer	HTTP status code of the response
message_code	String	Status message code
message	String	Human-readable status message
success	Boolean	Indicates if the request was successful

Example Successful API Response

{
  "data": {
    "client_id": "digilocker_puWsFhgqyuEpEdEWkxzm",
    "token": ".eJyrVkrOyUzNK4nPTFGyUkrJTM_MyU_OTi2KLygNL3bLSC-sLHUtcE1xDc-uqMpV0lFKTyxJLU-sBKotTsxLScqvAIqVVBakomhWqgUAeUcfZQ.ZfRPLA.61lSxiyFrRnRA_gO3XrVunVeGMs",
    "url": "https://digilocker-sdk.notbot.in/?gateway=sandbox&type=digilocker&token=.eJyrVkrOyUzNK4nPTFGyUkrJTM_MyU_OTi2KLygNL3bLSC-sLHUtcE1xDc-uqMpV0lFKTyxJLU-sBKotTsxLScqvAIqVVBakomhWqgUAeUcfZQ.ZfRPLA.61lSxiyFrRnRA_gO3XrVunVeGMs&auth_type=web",
    "expiry_seconds": 600
  },
  "status_code": 200,
  "message_code": "success",
  "message": "Success",
  "success": true
}

Example Webhook Response

Note: This is the response sent to your webhook URL, not the API response.

{
  "client_id": "digilocker_lbsfmoudALfjHnrowLCl",
  "status": "success",
  "type": "digilocker"
}

Possible Error Responses

Authentication Error

Validation Error

{
  "status_code": 401,
  "message_code": "unauthorized",
  "message": "Invalid or expired authentication token",
  "success": false
}

This error occurs when the JWT token is invalid, expired, or missing.

Integration Best Practices

Security Recommendations

Store the client_id and token securely as they provide access to user documents

Implement proper session management to handle token expiry

Use HTTPS for all communications, including the redirect URL

Validate all user inputs before sending to the API

User Experience Guidelines

Clearly explain to users why DigiLocker access is being requested

Provide clear instructions on the DigiLocker authentication process

Implement proper error handling and user-friendly error messages

Consider mobile responsiveness for the DigiLocker authentication flow

Code Samples

cURL

Python

Node.js

Related APIs

Get Status: Retrieve the current status of the DigiLocker OAuth flow

List Issued Documents: Fetch a list of issued documents from DigiLocker

Download Document: Download a specific document from DigiLocker using its file ID

Compliance and Legal Considerations

When integrating with DigiLocker, ensure compliance with the Information Technology Act, 2000 and the Aadhaar Act, 2016. Always obtain explicit user consent before accessing their DigiLocker documents. The integration must adhere to data protection guidelines and privacy regulations. User data obtained through this API should be handled securely and used only for the specified purpose.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/digilocker/initialize' \ --header 'Content-Type: application/json' \ --data-raw '{ "data": { "signup_flow": true, "redirect_url": "https://google.com" } }'

{ "data": { "client_id": "digilocker_puWsFhgqyuEpEdEWkxzm", "token": ".eJyrVkrOyUzNK4nPTFGyUkrJTM_MyU_OTi2KLygNL3bLSC-sLHUtcE1xDc-uqMpV0lFKTyxJLU-sBKotTsxLScqvAIqVVBakomhWqgUAeUcfZQ.ZfRPLA.61lSxiyFrRnRA_gO3XrVunVeGMs", "url": "https://digilocker-sdk.notbot.in/?gateway=sandbox&type=digilocker&token=.eJyrVkrOyUzNK4nPTFGyUkrJTM_MyU_OTi2KLygNL3bLSC-sLHUtcE1xDc-uqMpV0lFKTyxJLU-sBKotTsxLScqvAIqVVBakomhWqgUAeUcfZQ.ZfRPLA.61lSxiyFrRnRA_gO3XrVunVeGMs&auth_type=web", "expiry_seconds": 600 }, "status_code": 200, "message_code": "success", "message": "Success", "success": true }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Initialize via Link

Initialize DigiLocker Session#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request (Redirect URL)#

Example Request (Webhook URL)#

API Response Parameters#

Example Successful API Response#

Example Webhook Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses