Employment History from UAN

Endpoint Overview

POST /api/v1/income/employment-history-uan

Description

This API retrieves a user's complete employment history using their Universal Account Number (UAN). The UAN is a 12-digit number assigned by the Employees' Provident Fund Organisation (EPFO) in India to uniquely identify employees across different employers. This endpoint provides comprehensive employment details including current and previous employers, joining and exit dates, and PF contribution information.

Key Benefits

Instant verification of employment history without manual document checks

Access to official EPFO records for reliable employment verification

Comprehensive view of a user's professional background across multiple employers

Streamlined KYC and background verification processes

Use Cases

Financial Services

HR & Recruitment

Gig Economy

Verify employment stability for loan and credit card applications

Validate income sources for mortgage qualification

Assess employment history for insurance premium calculations

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 authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	12-digit UAN (Universal Account Number) of the employee

Example Request

{
    "id_number": "101669821230"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the employment history information
data.client_id	String	Unique identifier for the API request
data.uan	String	UAN number of the employee
data.employment_history	Array	List of employment records
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Additional information about the response (null if successful)
message_code	String	Code indicating the status of the response

Employment History Object

Parameter	Type	Description
name	String	Full name of the employee
guardian_name	String	Name of the employee's guardian
establishment_name	String	Name of the employer/company
member_id	String	EPFO member identification number
date_of_joining	String	Date when employee joined (YYYY-MM-DD format)
date_of_exit	String	Date when employee left (YYYY-MM-DD format), null if currently employed
last_pf_submitted	String	Date of last PF contribution (YYYY-MM-DD format)
wage_month	String	Month for which the last wage was processed

Example Successful Response

{
    "data": {
        "client_id": "employment_history_uan_aueTsCLbIqUDULtEFwZU",
        "uan": "111779821234",
        "employment_history": [
            {
                "name": "Munna Bhbaiya",
                "guardian_name": "Kaleen Bhaiya",
                "establishment_name": "I PROCESS SERVICES (INDIA) PVT. LTD.",
                "member_id": "KDMAL004123654000313079",
                "date_of_joining": "2021-03-15",
                "date_of_exit": null,
                "last_pf_submitted": "2022-06-14",
                "wage_month": "May-2022"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid UAN

Authentication Error

Service Unavailable

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

The UAN number provided is not in the correct format or doesn't exist in the EPFO database.

Integration Best Practices

Security Recommendations

Store UAN numbers securely and encrypt them at rest

Implement proper access controls for staff who can access employment history data

Do not store complete employment history in your database unless necessary

Implement rate limiting to prevent abuse of the API

User Experience Guidelines

Always obtain explicit consent from users before retrieving their employment history

Clearly communicate to users what data will be accessed and how it will be used

Provide a loading indicator during API calls as employment history retrieval may take a few seconds

Allow users to review their retrieved employment history for accuracy

Code Samples

cURL

Python

Node.js

Related APIs

Income Verification API: Verify income details using various income sources

PAN Verification API: Verify Permanent Account Number details

Bank Account Verification API: Verify bank account details and ownership

Employment Verification API: Verify current employment status through alternative sources

Compliance and Legal Considerations

This API accesses EPFO data which contains personally identifiable information (PII). Usage must comply with data protection regulations including:

Obtaining explicit user consent before accessing their UAN data

Storing and processing the data in compliance with India's data protection laws

Ensuring data is used only for the specific purpose communicated to the user

Implementing appropriate data retention and deletion policies

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/employment-history-uan' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "101669821230" }'

{ "data": { "client_id": "employment_history_uan_aueTsCLbIqUDULtEFwZU", "uan": "111779821234", "employment_history": [ { "name": "Munna Bhbaiya", "guardian_name": "Kaleen Bhaiya", "establishment_name": "I PROCESS SERVICES (INDIA) PVT. LTD.", "member_id": "KDMAL004123654000313079", "date_of_joining": "2021-03-15", "date_of_exit": null, "last_pf_submitted": "2022-06-14", "wage_month": "May-2022" } ] }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Employment History

Employment History from UAN#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Employment History Object#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses