Upload QR

Endpoint Overview

POST /api/v1/aadhaar/upload/qr

Description

This API endpoint allows you to verify Aadhaar QR codes and extract the information contained within them. By submitting the text content of an Aadhaar QR code, you can securely extract and validate the identity information encoded in the QR, including demographic details and photograph (if available). This endpoint provides a reliable method for digital KYC processes that require Aadhaar verification.

Key Benefits

Instant verification of Aadhaar QR codes without requiring physical document inspection

Secure extraction of demographic information from Aadhaar QR codes

Reduced manual data entry errors through automated data extraction

Compliant with UIDAI guidelines for Aadhaar data handling

Use Cases

Financial Services

Insurance

Telecom

Customer onboarding for bank accounts and loan applications

KYC verification for payment wallets and fintech applications

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	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
qr_text	String	Yes	The text content extracted from the Aadhaar QR code

Example Request

{
  "qr_text": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><PrintLetterBarcodeData uid=\"999941057058\" name=\"Some Name\" gender=\"M\" dateOfBirth=\"1990-01-01\" careOf=\"S/O: Father's Name\" building=\"\" street=\"\" landmark=\"\" locality=\"Some Locality\" vtcName=\"Some Village\" poName=\"Some Post Office\" districtName=\"Some District\" stateName=\"Some State\" pincode=\"123456\"/>"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the extracted Aadhaar information
data.aadhaar_number	String	Masked Aadhaar number
data.name	String	Name of the Aadhaar holder
data.dob	String	Date of birth in YYYY-MM-DD format
data.gender	String	Gender of the Aadhaar holder (M/F/T)
data.address	Object	Address details from the Aadhaar
data.address.care_of	String	Care of information
data.address.house	String	House number/name
data.address.street	String	Street name
data.address.landmark	String	Landmark information
data.address.locality	String	Locality information
data.address.vtc	String	Village/Town/City
data.address.district	String	District name
data.address.state	String	State name
data.address.pincode	String	Postal code
data.address.post_office	String	Post office name
data.image	String	Base64 encoded photograph (if available in QR)
data.qr_type	String	Type of QR code (Secure/Offline)
data.raw_xml	String	Raw XML data from the QR code
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 indicating the result type

Example Successful Response

{
    "data": {
        "aadhaar_number": "XXXX-XXXX-7058",
        "name": "Some Name",
        "dob": "1990-01-01",
        "gender": "M",
        "address": {
            "care_of": "S/O: Father's Name",
            "house": "",
            "street": "",
            "landmark": "",
            "locality": "Some Locality",
            "vtc": "Some Village",
            "district": "Some District",
            "state": "Some State",
            "pincode": "123456",
            "post_office": "Some Post Office"
        },
        "image": null,
        "qr_type": "Secure",
        "raw_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><PrintLetterBarcodeData uid=\"999941057058\" name=\"Some Name\" gender=\"M\" dateOfBirth=\"1990-01-01\" careOf=\"S/O: Father's Name\" building=\"\" street=\"\" landmark=\"\" locality=\"Some Locality\" vtcName=\"Some Village\" poName=\"Some Post Office\" districtName=\"Some District\" stateName=\"Some State\" pincode=\"123456\"/>"
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid QR

Authentication Error

{
    "status_code": 422,
    "success": false,
    "message": "Verification Failed.",
    "message_code": "verification_failed"
}

This error occurs when the provided QR text is not in the expected Aadhaar QR format.

Integration Best Practices

Security Recommendations

Store the extracted Aadhaar data in encrypted format

Implement proper access controls for systems handling Aadhaar information

Do not store the raw QR text longer than necessary for processing

Implement IP whitelisting for production API access

User Experience Guidelines

Provide clear instructions to users on how to scan Aadhaar QR codes

Implement proper error handling to guide users when QR scanning fails

Display a loading indicator during API processing

Allow users to verify the extracted information before proceeding

Code Samples

cURL

Python

Node.js

Related APIs

Aadhaar OCR API: Extract information from Aadhaar card images

Aadhaar Verification API: Verify Aadhaar number against UIDAI database

PAN Verification API: Verify PAN card details for KYC processes

Compliance and Legal Considerations

When handling Aadhaar data, ensure compliance with the Aadhaar Act, 2016 and UIDAI guidelines. Do not store Aadhaar numbers in plain text, and implement appropriate security measures to protect personal data. Organizations must have a valid agreement with UIDAI or work with an authorized Authentication User Agency (AUA) or KYC User Agency (KUA) to use Aadhaar data for verification purposes.

{ "data": { "aadhaar_number": "XXXX-XXXX-7058", "name": "Some Name", "dob": "1990-01-01", "gender": "M", "address": { "care_of": "S/O: Father's Name", "house": "", "street": "", "landmark": "", "locality": "Some Locality", "vtc": "Some Village", "district": "Some District", "state": "Some State", "pincode": "123456", "post_office": "Some Post Office" }, "image": null, "qr_type": "Secure", "raw_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><PrintLetterBarcodeData uid=\"999941057058\" name=\"Some Name\" gender=\"M\" dateOfBirth=\"1990-01-01\" careOf=\"S/O: Father's Name\" building=\"\" street=\"\" landmark=\"\" locality=\"Some Locality\" vtcName=\"Some Village\" poName=\"Some Post Office\" districtName=\"Some District\" stateName=\"Some State\" pincode=\"123456\"/>" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Upload QR

Upload QR#

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

Upload QR

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples