Upload eAadhaar

Endpoint Overview

POST /api/v1/aadhaar/upload/eaadhaar

Description

This API endpoint allows you to upload and verify an eAadhaar PDF document and extract the relevant personal information from it. The service validates the authenticity of the document, extracts the demographic details, and returns structured data that can be used for identity verification and KYC processes.

Key Benefits

Automated extraction of personal information from eAadhaar PDFs

Verification of document authenticity to prevent fraud

Structured data output for seamless integration with your KYC workflows

Compliant with UIDAI guidelines for Aadhaar data handling

Use Cases

Financial Services

Insurance

Telecom

Customer onboarding for banking and financial institutions

KYC verification for loan applications

Identity verification for opening new accounts

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 for authentication. Format: `Bearer <your_jwt_token>`
Content-Type	Yes	Must be set to `multipart/form-data`

Request Body

Parameter	Type	Required	Description
file	File	Yes	The eAadhaar PDF file to be uploaded and verified
base64	String	Yes	A base64 encoded string of the Aadhaar data.
yob	String	Yes	Year of Birth of the Aadhaar holder (optional).
full_name	String	Yes	Full name of the Aadhaar holder.

Example Request

'file=@"/path/to/file"' \
'base64=""' \
'yob=""' \
'full_name=""'

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the extracted Aadhaar information
data.aadhaar_number	String	The 12-digit Aadhaar number (partially masked)
data.name	String	Full name of the Aadhaar holder
data.dob	String	Date of birth in DD/MM/YYYY format
data.gender	String	Gender of the Aadhaar holder
data.address	String	Complete address as mentioned in the Aadhaar
data.face_status	Boolean	Indicates if a face image was successfully extracted
data.face	String	Base64 encoded image of the face extracted from the Aadhaar
data.split_address	Object	Address broken down into components
data.split_address.house	String	House number/name
data.split_address.street	String	Street name
data.split_address.landmark	String	Landmark information
data.split_address.locality	String	Locality or area
data.split_address.vtc	String	Village/Town/City
data.split_address.district	String	District name
data.split_address.state	String	State name
data.split_address.pincode	String	6-digit PIN code
data.phone	String	Phone number (if available in the Aadhaar)
data.email	String	Email address (if available in the Aadhaar)
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 1234",
    "name": "John Doe",
    "dob": "01/01/1990",
    "gender": "M",
    "address": "123, Sample Street, Landmark, City, District, State - 123456",
    "face_status": true,
    "face": "base64_encoded_image_data",
    "split_address": {
      "house": "123",
      "street": "Sample Street",
      "landmark": "Landmark",
      "locality": "",
      "vtc": "City",
      "district": "District",
      "state": "State",
      "pincode": "123456"
    },
    "phone": "9876543210",
    "email": "johndoe@example.com"
  },
  "status_code": 200,
  "success": true,
  "message": null,
  "message_code": "success"
}

Possible Error Responses

Invalid PDF

Authentication Error

{
    "status_code": 422,
    "success": false,
    "message": "Incorrect PDF or signature.",
    "message_code": null
}

This error occurs when the uploaded file is not a valid eAadhaar PDF document.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to manage API failures gracefully

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

Implement proper data retention policies for Aadhaar data in compliance with regulations

User Experience Guidelines

Clearly communicate to users why their eAadhaar document is being requested

Provide clear instructions on how to download their eAadhaar PDF from the UIDAI website

Implement a user-friendly interface for password input and document upload

Display appropriate loading indicators during the verification process

Code Samples

cURL

Python

Node.js

Related APIs

Aadhaar XML File Upload: Upload and verify Aadhaar XML files

Aadhaar OCR: Extract information from Aadhaar card images

Aadhaar Verification: Verify Aadhaar number against UIDAI database

Compliance and Legal Considerations

When handling Aadhaar data, ensure compliance with the Aadhaar Act, 2016 and UIDAI guidelines. Always obtain explicit user consent before processing Aadhaar information. Implement proper data security measures and follow data minimization principles. Do not store Aadhaar numbers in your database unless absolutely necessary and permitted by regulations.

{ "data": { "aadhaar_number": "XXXX XXXX 1234", "name": "John Doe", "dob": "01/01/1990", "gender": "M", "address": "123, Sample Street, Landmark, City, District, State - 123456", "face_status": true, "face": "base64_encoded_image_data", "split_address": { "house": "123", "street": "Sample Street", "landmark": "Landmark", "locality": "", "vtc": "City", "district": "District", "state": "State", "pincode": "123456" }, "phone": "9876543210", "email": "johndoe@example.com" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Upload eAadhaar

Upload eAadhaar#

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 eAadhaar

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples