Aadhaar To UAN

Endpoint Overview

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

Description

This API allows you to retrieve the Universal Account Number (UAN) associated with a given Aadhaar number. The UAN is a 12-digit number issued by the Employees' Provident Fund Organisation (EPFO) in India, which serves as a permanent identification for employees throughout their working career. This endpoint simplifies the process of finding a UAN when only the Aadhaar number is available.

Key Benefits

Instant UAN retrieval using just an Aadhaar number

Streamlines employee onboarding and verification processes

Reduces manual effort in EPFO-related compliance tasks

Enables automated verification of employment history

Use Cases

HR & Payroll

Financial Services

Government Services

Streamline employee onboarding by automatically retrieving UAN numbers

Verify employment history during background checks

Automate PF registration and compliance 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.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	Application/json

Request Body

Parameter	Type	Required	Description
aadhaar_number	String	Yes	The 12-digit Aadhaar number of the individual whose UAN needs to be retrieved

Example Request

{
    "aadhaar_number": "445025885514"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.aadhaar_number	String	The Aadhaar number provided in the request
data.client_id	String	Unique identifier for the API request
data.pf_uan	String	The UAN number associated with the provided Aadhaar number
status_code	Integer	HTTP status code indicating the result of the request
success	Boolean	Indicates whether the API call was successful
message	String or null	Additional information about the response (null if successful)
message_code	String	Code indicating the status of the request

Example Successful Response

{
    "data": {
        "aadhaar_number": "445905879514",
        "client_id": "aadhaar_to_uan_pvwoRJHGqcfpihFgrppF",
        "pf_uan": "101667814011"
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid Aadhaar

UAN Not Found

Authentication Error

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid Aadhaar number format",
    "message_code": "invalid_input"
}

The provided Aadhaar number is not in the correct format or fails validation.

Integration Best Practices

Security Recommendations

Store Aadhaar numbers in encrypted format and handle them as sensitive PII

Implement proper access controls to restrict who can make API calls

Use HTTPS for all API communications to ensure data is encrypted in transit

Rotate JWT tokens regularly and don't hardcode them in your applications

Implement IP whitelisting for additional security if supported by your infrastructure

User Experience Guidelines

Implement proper error handling to provide meaningful feedback to users

Add validation for Aadhaar number format before making API calls

Include loading indicators during API calls to improve user experience

Cache results where appropriate to improve performance for repeated lookups

Implement retry logic with exponential backoff for transient failures

Code Samples

cURL

Python

Node.js

Related APIs

EPFO UAN Verification API: Verify UAN details including name, date of birth, and employment status

EPFO PF Balance API: Retrieve PF balance information using UAN

Income Verification API: Verify employment and income details using UAN

Compliance and Legal Considerations

Aadhaar data is considered sensitive personal information under India's data protection laws

Ensure you have proper consent from individuals before accessing their Aadhaar-linked information

Maintain proper audit logs of all API calls for compliance with regulatory requirements

Usage of this API should comply with UIDAI guidelines for Aadhaar data handling

Ensure compliance with EPFO regulations regarding UAN data access and usage

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/income/epfo/aadhaar-to-uan' \ --header 'Authorization: Bearer TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "aadhaar_number": "445025885514" }'

{ "data": { "aadhaar_number": "445905879514", "client_id": "aadhaar_to_uan_pvwoRJHGqcfpihFgrppF", "pf_uan": "101667814011" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Aadhaar To UAN

Aadhaar To UAN#

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

Aadhaar To UAN

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples