Download Aadhaar from DigiLocker

Endpoint Overview

GET /api/v1/digilocker/download-aadhaar/<client_id>

Description

This API endpoint allows you to securely download Aadhaar details from DigiLocker using a unique client_id. Upon successful request, the API returns parsed Aadhaar XML data, key metadata, and a direct URL to the original XML file. This enables seamless integration of Aadhaar-based identity verification into your digital onboarding, KYC, or compliance workflows.

Key Benefits

Automates retrieval of Aadhaar data directly from DigiLocker, ensuring authenticity.

Provides both parsed data and original XML for maximum flexibility.

Reduces manual intervention and speeds up digital onboarding.

Enhances compliance with regulatory requirements for identity verification.

Use Cases

Banking & Financial Services

Telecommunications

Government & Public Sector

Instant digital KYC for new account opening.

Automated loan application verification using Aadhaar data.

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	Bearer token in the format `Bearer <JWT>`
Content-Type	No	`application/json` (recommended)

Request Body

This endpoint does not require a request body. All parameters are passed via the URL path.

Example Request

// No request body required for this GET endpoint.

Process Response

Response Parameters

Certainly! Here’s the revised response parameter table using dot notation for nested fields, as per your instruction:

Parameter	Type	Description
data	object	Contains the main Aadhaar data and metadata.
data.client_id	string	Unique DigiLocker client identifier.
data.digilocker_metadata	object	Basic metadata from DigiLocker.
data.digilocker_metadata.name	string	Name as per DigiLocker.
data.digilocker_metadata.gender	string	Gender (M/F/O).
data.digilocker_metadata.dob	string	Date of birth (YYYY-MM-DD).
data.aadhaar_xml_data	object	Parsed Aadhaar XML fields.
data.aadhaar_xml_data.full_name	string	Full name from Aadhaar.
data.aadhaar_xml_data.care_of	string	Care of (e.g., S/O, D/O, W/O).
data.aadhaar_xml_data.dob	string	Date of birth (YYYY-MM-DD).
data.aadhaar_xml_data.yob	string	Year of birth.
data.aadhaar_xml_data.zip	string	Postal code.
data.aadhaar_xml_data.profile_image	string	Base64-encoded profile image.
data.aadhaar_xml_data.gender	string	Gender (M/F/O).
data.aadhaar_xml_data.masked_aadhaar	string	Masked Aadhaar number.
data.aadhaar_xml_data.full_address	string	Complete address.
data.aadhaar_xml_data.father_name	string	Father's name or care of.
data.aadhaar_xml_data.address	object	Structured address fields.
data.aadhaar_xml_data.address.country	string	Country.
data.aadhaar_xml_data.address.dist	string	District.
data.aadhaar_xml_data.address.state	string	State.
data.aadhaar_xml_data.address.po	string	Post office.
data.aadhaar_xml_data.address.house	string	House number.
data.aadhaar_xml_data.address.loc	string	Locality.
data.aadhaar_xml_data.address.vtc	string	Village/Town/City.
data.aadhaar_xml_data.address.subdist	string	Sub-district.
data.aadhaar_xml_data.address.street	string	Street name.
data.aadhaar_xml_data.address.landmark	string	Landmark.
data.xml_url	string	URL to download the original Aadhaar XML file.
status_code	number	HTTP status code (e.g., 200 for success).
success	boolean	Indicates if the request was successful.
message	string	Human-readable status message
message_code	string	Machine-readable status code

Example Successful Response

{
  "data": {
    "client_id": "digilocker_12345ABCDE",
    "digilocker_metadata": {
      "name": "RAHUL KUMAR",
      "gender": "M",
      "dob": "1995-05-15"
    },
    "aadhaar_xml_data": {
      "full_name": "Rahul Kumar",
      "care_of": "S/O: Mohan Kumar",
      "dob": "1995-05-15",
      "yob": "1995",
      "zip": "110001",
      "profile_image": "base64_encoded_image_string",
      "gender": "M",
      "masked_aadhaar": "XXXXXXXX1234",
      "full_address": "Connaught Place, New Delhi, Delhi, India",
      "father_name": "S/O: Mohan Kumar",
      "address": {
        "country": "India",
        "dist": "New Delhi",
        "state": "Delhi",
        "po": "Connaught Place",
        "house": "12B",
        "loc": "Central Delhi",
        "vtc": "Connaught Place",
        "subdist": "New Delhi",
        "street": "Main Road",
        "landmark": "Near Metro Station"
      }
    },
    "xml_url": "https://dummy-url.com/rahul/aadhaar.xml"
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid or Missing Token

Invalid client_id

Aadhaar Data Already Downloaded

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

The request is missing a valid Bearer token or the token is invalid.

Integration Best Practices

Security Recommendations

Always use HTTPS to protect sensitive data in transit.

Store JWT tokens securely and rotate them periodically.

Never expose your API keys or tokens in client-side code or public repositories.

User Experience Guidelines

Display clear error messages to users in case of authentication or data retrieval failures.

Mask Aadhaar numbers and sensitive information in your UI.

Provide users with the option to download the original XML if required.

Code Samples

cURL

Python

Node.js

Related APIs

DigiLocker Aadhaar Consent API: Initiate Aadhaar consent flow for DigiLocker.

DigiLocker Document List API: Retrieve a list of documents available in DigiLocker.

Aadhaar XML Parsing API: Parse and validate Aadhaar XML files.

Compliance and Legal Considerations

Ensure you comply with all applicable data privacy laws and regulations (such as the Aadhaar Act and IT Act in India) when handling Aadhaar data. Do not store or process Aadhaar information beyond what is legally permitted. Always mask Aadhaar numbers in user interfaces and logs.

This documentation provides a comprehensive, implementation-focused guide for integrating the DigiLocker Aadhaar download API into your applications. For further support, refer to Surepass developer resources or contact your Surepass representative.

{ "data": { "client_id": "digilocker_12345ABCDE", "digilocker_metadata": { "name": "RAHUL KUMAR", "gender": "M", "dob": "1995-05-15" }, "aadhaar_xml_data": { "full_name": "Rahul Kumar", "care_of": "S/O: Mohan Kumar", "dob": "1995-05-15", "yob": "1995", "zip": "110001", "profile_image": "base64_encoded_image_string", "gender": "M", "masked_aadhaar": "XXXXXXXX1234", "full_address": "Connaught Place, New Delhi, Delhi, India", "father_name": "S/O: Mohan Kumar", "address": { "country": "India", "dist": "New Delhi", "state": "Delhi", "po": "Connaught Place", "house": "12B", "loc": "Central Delhi", "vtc": "Connaught Place", "subdist": "New Delhi", "street": "Main Road", "landmark": "Near Metro Station" } }, "xml_url": "https://dummy-url.com/rahul/aadhaar.xml" }, "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 ********************

⭐️ Download Aadhaar

Download Aadhaar from DigiLocker#

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