UAN List

Endpoint Overview

POST /api/v1/income/epfo/find-uan-list

Description

This API endpoint allows you to retrieve a list of Universal Account Numbers (UANs) associated with a specific mobile number from the Employees' Provident Fund Organisation (EPFO) database. It provides a simple and efficient way to identify all PF accounts linked to a particular mobile number, enabling streamlined verification and integration with EPFO services.

Key Benefits

Quickly identify all UAN numbers associated with a single mobile number

Simplify user onboarding by automatically retrieving UAN information

Reduce manual data entry errors in financial and HR applications

Enable seamless integration with EPFO-related services

Use Cases

Financial Services

HR & Payroll

Government Services

Verify employment history during loan application processing

Automate KYC verification for financial product onboarding

Streamline pension and retirement account management

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
mobile_number	String	Yes	The mobile number associated with UAN accounts to be retrieved

Example Request

{
    "mobile_number": "8191812345"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.pf_uan	Array	List of UAN numbers associated with the provided mobile number
data.client_id	String	Unique identifier for the client making the request
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates whether the request 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": {
        "pf_uan": [
            "100189512345",
            "100979312345"
        ],
        "client_id": "income_uan_lookup_VkThahxarFLEHFCabSPt"
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number

No UAN Found

Authentication Error

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

The mobile number provided is not in a valid format. Ensure it is a 10-digit number without any special characters.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to prevent sensitive information leakage

Rotate JWT tokens regularly and implement token expiration policies

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

User Experience Guidelines

Implement caching strategies to improve response times for frequently accessed UAN data

Provide clear error messages to users when mobile numbers don't match any UAN records

Include loading indicators during API calls to improve perceived performance

Validate mobile number format on the client-side before making API requests

Code Samples

cURL

Python

Node.js

Related APIs

EPFO UAN Verification API: Verifies the validity of a specific UAN number

EPFO Passbook API: Retrieves PF contribution history using a UAN number

EPFO KYC Status API: Checks the KYC status of a UAN account

Compliance and Legal Considerations

This API accesses EPFO data which contains personally identifiable information (PII). Ensure you have proper consent from users before retrieving their UAN information. Usage of this API must comply with relevant data protection regulations including but not limited to the Information Technology Act, 2000 and the Personal Data Protection Bill. Maintain appropriate data security measures and retention policies for any retrieved information.

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/epfo/find-uan-list' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "mobile_number": "8191812345" }'

{ "data": { "pf_uan": [ "100189512345", "100979312345" ], "client_id": "income_uan_lookup_VkThahxarFLEHFCabSPt" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

UAN List

UAN List#

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

UAN List

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples