List Documents

Endpoint Overview

GET /api/v1/digilocker/list-documents/{digilocker_client_id}

Description

This API endpoint retrieves a comprehensive list of all documents stored in a user's DigiLocker account. It provides detailed information about each document, including document type, issuer details, and download status. This endpoint is essential for applications that need to access and manage user documents from DigiLocker for verification, processing, or display purposes.

Key Benefits

Seamless access to users' official documents without manual uploads

Verification of document authenticity as they come directly from DigiLocker

Simplified document collection process for KYC and onboarding workflows

Reduced operational overhead by eliminating manual document handling

Use Cases

Financial Services

Healthcare

Government Services

Streamline customer onboarding by retrieving identity documents for KYC verification

Access tax documents for loan processing and credit assessment

Verify income certificates and financial statements for account opening

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_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 session

Request Body

This endpoint does not require a request body.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.documents	Array	List of document objects retrieved from DigiLocker
data.documents[].file_id	String	Unique identifier for the document file
data.documents[].name	String	Name of the document
data.documents[].doc_type	String	Type code of the document (e.g., "PANCR", "ADHAR")
data.documents[].downloaded	Boolean	Indicates whether the document has been downloaded
data.documents[].issuer	String	Organization that issued the document
data.documents[].description	String	Brief description of the document
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates whether the API call was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "documents": [
            {
                "file_id": "digilocker_file_PjorZrpBQQSSbquyTPav",
                "name": "PAN Verification Record",
                "doc_type": "PANCR",
                "downloaded": true,
                "issuer": "Income Tax Department",
                "description": "PAN Verification Record"
            },
            {
                "file_id": "digilocker_file_gjMycCOuvUTyifttXXDk",
                "name": "Aadhaar Card",
                "doc_type": "ADHAR",
                "downloaded": true,
                "issuer": "Unique Identification Authority of India (UIDAI)",
                "description": "Aadhaar Card"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Client ID Error

Server Error

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

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

Integration Best Practices

Security Recommendations

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

Implement proper token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Provide clear instructions to users about connecting their DigiLocker account

Implement proper loading states while fetching documents from DigiLocker

Allow users to select which documents they want to share from the list

Display document information in a user-friendly format with appropriate icons

Code Samples

cURL

Python

Node.js

Related APIs

Download Document API - Retrieves the actual document file using the file_id

DigiLocker Authentication API - Initiates the DigiLocker authentication flow

DigiLocker Callback API - Handles the callback after DigiLocker authentication

Document Verification API - Verifies the authenticity of documents retrieved from DigiLocker

Compliance and Legal Considerations

When accessing documents from DigiLocker, ensure you have explicit user consent for retrieving and processing their documents. The use of DigiLocker documents is subject to DigiLocker's terms of service and India's Electronic Consent Framework. Ensure compliance with data protection regulations like the Personal Data Protection Bill when storing or processing these documents. Documents should only be accessed for the specific purpose communicated to and agreed upon by the user.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "documents": [ { "file_id": "digilocker_file_PjorZrpBQQSSbquyTPav", "name": "PAN Verification Record", "doc_type": "PANCR", "downloaded": true, "issuer": "Income Tax Department", "description": "PAN Verification Record" }, { "file_id": "digilocker_file_gjMycCOuvUTyifttXXDk", "name": "Aadhaar Card", "doc_type": "ADHAR", "downloaded": true, "issuer": "Unique Identification Authority of India (UIDAI)", "description": "Aadhaar Card" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

List Documents

List Documents#

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

List Documents

Description

Use Cases

Technical Implementation

Request Headers

Path Parameters

Request Body

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples