Employment History Report

Endpoint Overview

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

Description

This API retrieves a comprehensive employment history report for a user based on their Universal Account Number (UAN). The report includes detailed employment records, establishment information, and tenure details extracted from the Employees' Provident Fund Organization (EPFO) database. The API returns both structured data for programmatic use and a formatted PDF report for documentation purposes.

Key Benefits

Instant verification of employment history without manual document collection

Access to official EPFO records for reliable employment verification

Comprehensive details including joining dates, exit dates, and last PF contribution

Ready-to-use PDF report with customizable branding options

Use Cases

Financial Services

HR & Recruitment

Insurance

Verify employment stability during loan underwriting processes

Validate income consistency for credit card applications

Confirm employment claims during mortgage qualification

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	UAN (Universal Account Number) of the employee
partner_url	String	No	URL of your company logo to be displayed in the PDF report (defaults to Surepass logo if not provided)

Example Request

{
    "id_number": "101669821234"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
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
data.employment_history_report	String	URL to download the PDF report
status_code	Number	HTTP status code
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code representing the response message

Employment History Object

Parameter	Type	Description
name	String	Employee's full name
guardian_name	String	Employee's guardian/parent name
establishment_name	String	Name of the employer/company
member_id	String	EPFO member identification number
date_of_joining	String	Employment start date (YYYY-MM-DD format)
date_of_exit	String	Employment end date (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 reported

Example Successful Response

{
    "data": {
        "client_id": "employment_history_uan_report_OCwovwWzxRixClfsOADY",
        "uan": "111779821234",
        "employment_history": [
            {
                "name": "Munna Bhaiya",
                "guardian_name": "Kaleen Bhaiya",
                "establishment_name": "I PROCESS SERVICES (INDIA) PVT. LTD.",
                "member_id": "KDMAL00478080000313079",
                "date_of_joining": "2021-03-15",
                "date_of_exit": null,
                "last_pf_submitted": "2022-06-14",
                "wage_month": "May-2022"
            }
        ],
        "employment_history_report": "https://aadhaar-kyc-docs.s3.amazonaws.com/vishal.rathore.surepass/employment_history_uan/employment_history_uan_report_OCwovwWzxRixClfsOADY/X-Amz-Signature=c312b481406e47bd5695360296d8b05c1e77fbae910cdcf743d1a66ea039f9ba"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid UAN

UAN Not Found

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid UAN number provided",
    "message_code": "invalid_uan"
}

The UAN number provided is not valid or does not match the required format.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to prevent sensitive information leakage

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

Implement IP whitelisting for additional security when accessing the API

User Experience Guidelines

Implement proper loading states while waiting for the API response

Cache employment history data when appropriate to improve performance

Provide clear error messages to end-users when verification fails

Allow users to download the PDF report directly from your application

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API: Verify PAN card details for identity verification

Aadhaar Verification API: Verify Aadhaar card details for identity verification

Bank Account Verification API: Verify bank account details for financial verification

Income Tax Return API: Retrieve income tax return data for income verification

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 employment history. Usage of this data must comply with applicable data protection regulations including but not limited to the Information Technology Act, 2000 and the Personal Data Protection Bill. Store and process the retrieved data securely and use it only for the disclosed purpose.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/income/employment-history-uan-report' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "101669821234" }'

{ "data": { "client_id": "employment_history_uan_report_OCwovwWzxRixClfsOADY", "uan": "111779821234", "employment_history": [ { "name": "Munna Bhaiya", "guardian_name": "Kaleen Bhaiya", "establishment_name": "I PROCESS SERVICES (INDIA) PVT. LTD.", "member_id": "KDMAL00478080000313079", "date_of_joining": "2021-03-15", "date_of_exit": null, "last_pf_submitted": "2022-06-14", "wage_month": "May-2022" } ], "employment_history_report": "https://aadhaar-kyc-docs.s3.amazonaws.com/vishal.rathore.surepass/employment_history_uan/employment_history_uan_report_OCwovwWzxRixClfsOADY/X-Amz-Signature=c312b481406e47bd5695360296d8b05c1e77fbae910cdcf743d1a66ea039f9ba" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Employment History Report

Employment History Report#

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

Employment History Report

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