Aadhaar to UAN Lite API

Endpoint Overview

POST /api/v1/income/aadhaar-to-uan-lite

Description

The Aadhaar to UAN Lite API enables seamless retrieval of Universal Account Numbers (UAN) using Aadhaar numbers. This lightweight endpoint provides a streamlined way to link an individual's Aadhaar identity with their Provident Fund (PF) account information through the UAN system. The API returns masked sensitive information to ensure privacy while providing the essential linking data needed for employment verification and financial services.

This service is particularly valuable for organizations requiring quick verification of employee PF account details, HR departments managing employee onboarding, and financial institutions needing to validate employment-related information.

Key Benefits

Instant Verification: Get UAN details in real-time using just the Aadhaar number

Privacy Protection: Returns masked sensitive data to maintain user privacy and comply with data protection regulations

Lightweight Process: Streamlined endpoint designed for quick integration and fast response times

Employment Validation: Essential for HR processes, loan applications, and employment verification workflows

Use Cases

Human Resources

Financial Services

Government & Compliance

Employee onboarding verification to confirm PF account linkage

Bulk employee verification for existing workforce management

Compliance checks for statutory benefit enrollment

Background verification during recruitment processes

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.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token containing your JWT for API authentication
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	12-digit Aadhaar number for which UAN information needs to be retrieved

Example Request

{
  "id_number": "922809384123"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object holding the API response data
data.client_id	String	Unique identifier for this API request transaction
data.id_number	String	Masked Aadhaar number showing only the last 4 digits
data.uan	String	Masked Universal Account Number showing only the last 4 digits
status_code	Integer	HTTP status code indicating the result of the API call
success	Boolean	Flag indicating whether the API call was successful
message	String/Null	Additional message providing context about the response
message_code	String	Standardized code representing the response status

Example Successful Response

{
  "data": {
    "client_id": "aadhaar_to_uan_lite_PDjfzaRSrtMtomuikMWL",
    "id_number": "XXXXXXXX4123",
    "uan": "XXXXXXXX8265"
  },
  "status_code": 200,
  "success": true,
  "message": null,
  "message_code": "success"
}

Possible Error Responses

Invalid Aadhaar

Authentication Error

{
    "status_code": 422,
    "success": false,
    "message": "Invalid Aadhaar Number",
    "message_code": "invalid_aadhaar_number"
}

Returned when the provided Aadhaar number is invalid or incorrect.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and implement proper token rotation mechanisms

Validate Aadhaar numbers on the client side before making API calls to reduce unnecessary requests

Implement rate limiting to prevent API abuse and ensure compliance with usage policies

Log API transactions securely while avoiding storage of sensitive personal information

User Experience Guidelines

Provide clear error messages to users when Aadhaar verification fails

Implement proper loading states during API calls as network latency may vary

Cache successful responses appropriately to improve performance for repeat queries

Ensure user consent is obtained before processing Aadhaar information for compliance

Code Samples

cURL

Python

Node.js

Related APIs

PAN to UAN: Retrieve UAN information using PAN card details

UAN Details: Get comprehensive UAN account information and employment history

Aadhaar Verification: Basic Aadhaar validation and demographic information

Employment Verification: Complete employment verification using multiple document types

Compliance and Legal Considerations

This API processes Aadhaar information and is subject to UIDAI guidelines and data protection regulations. Ensure proper user consent is obtained before processing personal information. The API returns masked data to maintain privacy compliance. Organizations using this API must implement appropriate data handling and storage practices in accordance with applicable privacy laws and regulations.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/income/aadhaar-to-uan-lite' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "922809384123" }'

{ "data": { "client_id": "aadhaar_to_uan_lite_PDjfzaRSrtMtomuikMWL", "id_number": "XXXXXXXX4123", "uan": "XXXXXXXX8265" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Aadhaar To UAN Lite

Aadhaar to UAN Lite API#

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