Get DigiLocker Status

Endpoint Overview

GET /api/v1/digilocker/status/{digilocker_client_id}

Description

This endpoint retrieves the current OAuth status of a DigiLocker integration for a specific client. It provides information about whether the DigiLocker authentication flow has been completed, if it failed, and whether the user's Aadhaar card is linked to their DigiLocker account. This API is essential for tracking the progress and status of DigiLocker authentication flows in your application.

Key Benefits

Real-time status tracking of DigiLocker authentication flows

Verification of Aadhaar linkage status for enhanced identity verification

Simple integration for monitoring user progress through the DigiLocker authentication process

Reliable error detection to improve user experience during authentication failures

Use Cases

Financial Services

Government Services

Healthcare

Monitor customer KYC verification status during account opening

Track DigiLocker document retrieval progress for loan applications

Verify Aadhaar linkage for regulatory compliance in financial transactions

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.io

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: `Bearer <your_jwt_token>`
Content-Type	Yes	Set to `application/json`

Path Parameters

Parameter	Type	Required	Description
client_id	String	Yes	The unique identifier for the DigiLocker client whose status you want to check

Request Body

No request body is required for this endpoint.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the status information
data.error_description	String/null	Description of any error that occurred during the DigiLocker flow, null if no error
data.status	String	Current status of the DigiLocker flow (e.g., "completed", "pending", "failed")
data.completed	Boolean	Indicates whether the DigiLocker flow has been completed
data.failed	Boolean	Indicates whether the DigiLocker flow has failed
data.aadhaar_linked	Boolean	Indicates whether the user's Aadhaar card is linked to their DigiLocker account
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates whether the API request was successful
message	String	Human-readable message describing the result
message_code	String	Machine-readable code representing the message

Example Successful Response

{
    "data": {
        "error_description": null,
        "status": "completed",
        "completed": true,
        "failed": false,
        "aadhaar_linked": true
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

{
    "data": null,
    "status_code": 404,
    "success": false,
    "message": "DigiLocker client not found",
    "message_code": "client_not_found"
}

This error occurs when the provided digilocker_client_id does not exist in the system.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration gracefully

Use HTTPS for all API communications to ensure data security

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Poll this endpoint at reasonable intervals when waiting for a user to complete DigiLocker authentication

Display appropriate loading states while checking status to keep users informed

Provide clear error messages to users when authentication fails

Implement proper retry mechanisms with backoff strategies for temporary failures

Code Samples

cURL

Python

Node.js

Related APIs

DigiLocker Initialize API: Creates a new DigiLocker authentication session

DigiLocker Documents API: Retrieves documents from a user's DigiLocker account

DigiLocker Webhook API: Receives real-time notifications about DigiLocker authentication events

Compliance and Legal Considerations

When using DigiLocker APIs, ensure compliance with the DigiLocker Terms of Service and the Aadhaar Act. User consent must be obtained before accessing their DigiLocker data. All personal data retrieved must be handled in accordance with applicable data protection regulations, including but not limited to the Information Technology Act and potential Personal Data Protection laws in India.

{ "data": { "error_description": null, "status": "completed", "completed": true, "failed": false, "aadhaar_linked": true }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Get Status

Get DigiLocker Status#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Request Body#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses