Digilocker Verify Account

Endpoint Overview

POST /api/v1/digilocker/verify-account

Description

The DigiLocker Account Verification API enables businesses to verify whether a user has an active DigiLocker account before initiating document retrieval or authentication workflows. This endpoint accepts either an Aadhaar ID number or mobile number and returns the account status along with associated DigiLocker credentials.

DigiLocker is India's digital document storage platform that allows citizens to securely store and share verified documents issued by government agencies. This API serves as a preliminary check to ensure users have registered with DigiLocker, streamlining the digital verification process and reducing failed authentication attempts.

Key Benefits

Pre-validation: Verify DigiLocker account existence before initiating document fetch operations, reducing unnecessary API calls and improving user experience

Flexible Query Options: Search using either Aadhaar ID number or registered mobile number for maximum convenience

Real-time Verification: Instant account status confirmation enabling seamless integration into digital onboarding workflows

Cost Optimization: Avoid failed verification attempts by confirming account existence upfront

Use Cases

Financial Services

Government Services

EdTech & HR

Digital Onboarding: Banks and NBFCs can verify DigiLocker accounts during customer onboarding to enable instant document verification

Loan Application Processing: Pre-check DigiLocker availability before requesting income documents, reducing application abandonment rates

KYC Compliance: Streamline KYC processes by confirming document availability through DigiLocker before initiating verification

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 YOUR_JWT_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	JWT Bearer token for authentication. Format: `Bearer YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	string	Conditional	Aadhaar ID number to verify DigiLocker account. Either `id_number` or `mobile_number` must be provided
mobile_number	string	Conditional	Registered mobile number to verify DigiLocker account. Either `id_number` or `mobile_number` must be provided

Note: You must provide either id_number OR mobile_number in the request. Both parameters should not be sent simultaneously.

Example Request

{
    "id_number": "6209XXXXXXXX"
}

Alternative Request with Mobile Number:

{
    "mobile_number": "9XXXXXXXXX"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding verification results
data.id_number	string	Masked Aadhaar ID number associated with the DigiLocker account
data.mobile_number	string/null	Registered mobile number if queried by mobile, otherwise null
data.account_exist	boolean	Indicates whether a DigiLocker account exists for the provided identifier
data.digilocker_id	string	Unique DigiLocker account identifier for the user
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the API call was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the message

Example Successful Response

{
    "data": {
        "id_number": "XXXXXXXX1234",
        "mobile_number": null,
        "account_exist": true,
        "digilocker_id": "eb529dce-0c72-9b0d-f11ca23"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Account Not Found

Authentication Error

Invalid Request

Server Error

{
    "data": {
        "id_number": "XXXXXXXX1234",
        "mobile_number": null,
        "account_exist": false,
        "digilocker_id": ""
    },
    "status_code": 200,
    "success": true,
    "message": "No DigiLocker account found",
    "message_code": "account_not_found"
}

The provided ID number or mobile number does not have an associated DigiLocker account.

Integration Best Practices

Security Recommendations

Token Security: Store JWT tokens securely using environment variables or secure vaults. Never expose tokens in client-side code or version control systems

HTTPS Only: Always use HTTPS endpoints to encrypt data in transit and protect sensitive user information

Data Masking: The API returns masked ID numbers by default. Ensure any displayed data maintains this privacy standard in your UI

Rate Limiting: Implement exponential backoff for retries to avoid overwhelming the API during high-traffic scenarios

Audit Logging: Maintain detailed logs of all verification requests for compliance and debugging purposes

User Experience Guidelines

Progressive Disclosure: Use this API as a pre-check before prompting users to connect their DigiLocker account, reducing frustration from failed attempts

Clear Messaging: If account doesn't exist, provide helpful guidance on how users can create a DigiLocker account

Fallback Options: Offer alternative verification methods if a user doesn't have a DigiLocker account

Loading States: Display appropriate loading indicators during API calls to manage user expectations

Error Handling: Provide user-friendly error messages that guide users on corrective actions rather than exposing technical details

Code Samples

cURL

Python

Node.js

Related APIs

DigiLocker Document Fetch API - Retrieve verified documents from a user's DigiLocker account after confirming account existence

Aadhaar Verification API - Perform comprehensive Aadhaar validation including demographic and biometric verification

DigiLocker eSign API - Enable users to digitally sign documents using their DigiLocker credentials

Mobile Number Verification API - Validate mobile numbers independently before using them for DigiLocker account lookup

Compliance and Legal Considerations

This API processes sensitive personal information including Aadhaar numbers and mobile numbers. Ensure your implementation complies with:

Aadhaar Act, 2016: Obtain explicit user consent before collecting or processing Aadhaar numbers. Store Aadhaar data in encrypted format only

IT Act, 2000 & Rules: Implement reasonable security practices to protect user data from unauthorized access

Data Protection: Follow data minimization principles - only collect and retain data necessary for the stated purpose

User Consent: Maintain clear records of user consent for DigiLocker account verification

Purpose Limitation: Use verification results only for the specific purpose disclosed to and consented by the user

Consult with legal counsel to ensure full compliance with applicable regulations in your jurisdiction.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/digilocker/verify-account' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "6209XXXXXXXX" }'

{ "data": { "id_number": "XXXXXXXX1234", "mobile_number": null, "account_exist": true, "digilocker_id": "eb529dce-0c72-9b0d-f11ca23" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Verify Account

Digilocker Verify Account#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses