Upload XML

Endpoint Overview

POST /api/v1/aadhaar/upload/xml

Description

This endpoint allows you to upload and verify Aadhaar XML files to extract and validate user identity information. The API parses the XML file, extracts demographic and biometric details, and returns structured data that can be used for identity verification and KYC processes. This service helps businesses streamline their customer onboarding by leveraging official Aadhaar data in a secure and compliant manner.

Key Benefits

Instant verification of Aadhaar XML data without manual intervention

Structured extraction of demographic details for seamless integration with your systems

Reduced risk of fraud through cryptographic verification of XML authenticity

Compliance with UIDAI guidelines for Aadhaar data handling

Use Cases

Financial Services

Insurance

Telecom

Customer onboarding for bank accounts and loan applications

eKYC verification for digital wallets and payment services

Secure authentication for high-value 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	Bearer token for authentication (JWT format)
Content-Type	Yes	Must be set to `multipart/form-data`

Request Body

Parameter	Type	Required	Description
file	File	Yes	The Aadhaar XML file to be uploaded and verified
consent	String	Yes	User consent for processing Aadhaar data (value: "Y")
consent_text	String	Yes	Text describing the consent given by the user

Example Request

'file=@"/path/to/file"' \
'base64=""' \
'share_code=""'

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the extracted Aadhaar information
data.aadhaar_number	String	Masked Aadhaar number of the individual
data.name	String	Full name as per Aadhaar record
data.dob	String	Date of birth in YYYY-MM-DD format
data.gender	String	Gender of the individual (M/F/T)
data.address	Object	Address details from Aadhaar
data.address.country	String	Country of residence
data.address.dist	String	District of residence
data.address.house	String	House number/name
data.address.landmark	String	Landmark near residence (if available)
data.address.loc	String	Locality information
data.address.pc	String	Postal code (PIN code)
data.address.po	String	Post office name
data.address.state	String	State of residence
data.address.street	String	Street name
data.address.subdist	String	Sub-district information
data.address.vtc	String	Village/Town/City
data.face_status	Boolean	Indicates if face biometric is available
data.face	String	Base64 encoded face image (if available)
data.xml_timestamp	String	Timestamp of XML generation
data.verification_timestamp	String	Timestamp of verification
data.reference_id	String	Unique reference ID for this verification
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": "1990-01-01",
    "gender": "M",
    "address": {
      "country": "India",
      "dist": "Bangalore",
      "house": "42",
      "landmark": "Near City Park",
      "loc": "Koramangala",
      "pc": "560034",
      "po": "Koramangala",
      "state": "Karnataka",
      "street": "5th Block",
      "subdist": "Bangalore South",
      "vtc": "Bangalore"
    },
    "face_status": true,
    "face": "base64EncodedImageData...",
    "xml_timestamp": "2023-05-15T10:30:45+05:30",
    "verification_timestamp": "2023-05-15T10:31:12+05:30",
    "reference_id": "sp-aadhar-xml-12345-abcde"
  },
  "status_code": 200,
  "success": true,
  "message": null,
  "message_code": "success"
}

Possible Error Responses

Invalid XML

Authentication Error

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

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

Integration Best Practices

Security Recommendations

Store the JWT token securely and never expose it in client-side code

Implement proper error handling to manage API failures gracefully

Encrypt Aadhaar XML files during storage and transmission

Delete Aadhaar data after verification is complete to comply with data minimization principles

User Experience Guidelines

Clearly communicate to users that their Aadhaar data is being processed

Obtain explicit consent before uploading Aadhaar XML

Provide clear instructions on how to download their Aadhaar XML from the UIDAI website

Implement a progress indicator during the verification process

Code Samples

cURL

Python

Node.js

Related APIs

Aadhaar OCR Verification: Extract and verify information from Aadhaar card images

Aadhaar Number Verification: Verify Aadhaar numbers through OTP authentication

Aadhaar QR Code Verification: Extract and verify information from Aadhaar QR codes

Compliance and Legal Considerations

When handling Aadhaar data, ensure compliance with the Aadhaar Act, 2016 and UIDAI guidelines. Store Aadhaar data securely and only for the duration necessary for verification. Always obtain explicit user consent before processing Aadhaar information, and maintain proper audit trails of all verification activities. Businesses must have a valid agreement with an Authorized Service Agency (ASA) or Authentication User Agency (AUA) to legally process Aadhaar data.

{ "data": { "aadhaar_number": "XXXX XXXX 1234", "name": "John Doe", "dob": "1990-01-01", "gender": "M", "address": { "country": "India", "dist": "Bangalore", "house": "42", "landmark": "Near City Park", "loc": "Koramangala", "pc": "560034", "po": "Koramangala", "state": "Karnataka", "street": "5th Block", "subdist": "Bangalore South", "vtc": "Bangalore" }, "face_status": true, "face": "base64EncodedImageData...", "xml_timestamp": "2023-05-15T10:30:45+05:30", "verification_timestamp": "2023-05-15T10:31:12+05:30", "reference_id": "sp-aadhar-xml-12345-abcde" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Upload XML

Upload XML#

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 XML

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples