Mobile to UAN

Endpoint Overview

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

Description

This API allows you to retrieve a Universal Account Number (UAN) associated with a given mobile number. The UAN is a unique 12-digit number assigned to employees covered under the Employees' Provident Fund (EPF) scheme in India. This endpoint simplifies the process of finding a UAN when only the mobile number is available, eliminating the need for manual verification through EPFO portals.

Key Benefits

Instant UAN retrieval using just a mobile number

Streamlined verification process for employment and income verification

Reduces manual effort and potential errors in UAN identification

Enables automated workflows for financial services and HR systems

Use Cases

Financial Services

HR & Payroll

Insurance

Loan eligibility verification by confirming formal employment status

Income verification for credit assessment using EPFO data

KYC enhancement by validating employment details

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 the UAN (10 digits)

Example Request

{
    "mobile_number": "8079028529"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the retrieved UAN information
data.pf_uan	String	The 12-digit Universal Account Number
data.client_id	String	Unique identifier for the request
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String or null	Additional information about the response
message_code	String	Code indicating the status of the request

Example Successful Response

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

Possible Error Responses

Invalid Mobile Number

UAN Not 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 10-digit format.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications to ensure data encryption

Implement rate limiting in your application to prevent abuse

User Experience Guidelines

Validate mobile number format before making API calls

Implement appropriate loading states while waiting for API response

Provide clear error messages to end-users when UAN retrieval fails

Cache results when appropriate to improve response times

Code Samples

cURL

Python

Node.js

Related APIs

EPFO Employment History API: Retrieve employment history using UAN

EPFO Contribution Details API: Get contribution details for a UAN

Income Verification API: Verify income details using UAN and other identifiers

Compliance and Legal Considerations

This API accesses EPFO data which contains personal information. Ensure you have proper consent from users before retrieving their UAN. Usage of this API must comply with applicable data protection laws including but not limited to the Information Technology Act, 2000 and the Personal Data Protection Bill. Ensure that you maintain appropriate data security measures and privacy policies when handling the retrieved information.

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

{ "data": { "pf_uan": "101667814011", "client_id": "income_uan_lookup_ackopQnlrOjwRPcFWPWV" }, "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 ********************

Mobile to UAN

Mobile 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

Mobile 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