Employment History By UAN V2 Report

Endpoint Overview

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

Description

The Employment History UAN V2 Report API enables businesses to retrieve comprehensive employment records associated with a Universal Account Number (UAN) from the Employees' Provident Fund Organisation (EPFO) database. This API provides detailed information about an individual's employment journey, including current and previous employers, joining and exit dates, and member identification details.

This endpoint returns both structured JSON data and a downloadable PDF report, making it ideal for background verification, loan processing, employment verification, and HR due diligence processes. The API leverages official EPFO records to provide authentic and up-to-date employment information. Additionally, it supports custom branding through an optional partner logo parameter that can be embedded in the generated PDF report.

Key Benefits

Comprehensive Employment Timeline: Access complete employment history with dates of joining and exit for all registered establishments

Official EPFO Records: Retrieve verified data directly from EPFO's Universal Account Number database

Dual Format Output: Receive both structured JSON data for automated processing and a PDF report for documentation

Custom Branding Support: Generate PDF reports with your partner logo for white-label solutions and enhanced brand presence

Use Cases

Financial Services

Human Resources

Insurance & Compliance

Loan Application Processing: Verify employment stability and income consistency for personal loan, home loan, and credit card applications

Credit Risk Assessment: Evaluate employment continuity and job-hopping patterns to assess borrower reliability

Income Verification: Validate employment claims made in loan applications with official EPFO records

Branded Verification Reports: Generate employment verification reports with financial institution branding for customer documentation

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.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for API authentication. Format: `Bearer {token}`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	string	Yes	12-digit Universal Account Number (UAN) issued by EPFO to the employee
partner_url	string	No	Optional URL of partner logo image to be included in the generated PDF report. Use publicly accessible image URL (e.g., PNG, JPG format)

Example Request

{
    "id_number": "123456789012",
    "partner_url": "https://i.postimg.cc/JnCKgLhn.png"
}

Note: The partner_url parameter is optional. When provided, the PDF report will include your partner logo for branded documentation. If omitted, the PDF will be generated with default styling.

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding all employment history information
data.client_id	string	Unique identifier for this API request transaction
data.uan	string	The Universal Account Number that was queried
data.employment_history	array	Array of employment records associated with the UAN
data.employment_history[].name	string	Employee's name as registered with EPFO
data.employment_history[].guardian_name	string	Father's or guardian's name as per EPFO records
data.employment_history[].establishment_name	string	Name of the employer/establishment
data.employment_history[].member_id	string	Unique member identification number for the establishment
data.employment_history[].date_of_joining	string	Date when employee joined the establishment (YYYY-MM-DD format)
data.employment_history[].date_of_exit	string	Date when employee exited the establishment (YYYY-MM-DD format)
data.employment_history_report	string	Pre-signed S3 URL to download the PDF report (valid for 600 seconds)
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the API call was successful
message	string	Human-readable message describing the response status
message_code	string	Machine-readable code for the response status

Example Successful Response

{
    "data": {
        "client_id": "employment_history_uan_v2_report_bbxduPdlQTsqcIjIIIsl",
        "uan": "123456789012",
        "employment_history": [
            {
                "name": "MUNNA TRIPATHI",
                "guardian_name": "KALEEN TRIPATHI",
                "establishment_name": "ABC SERVICES PRIVATE LIMITED",
                "member_id": "FGHIJ01234567890123456",
                "date_of_joining": "2024-09-01",
                "date_of_exit": "2025-12-05"
            },
            {
                "name": "MUNNA TRIPATHI",
                "guardian_name": "KALEEN TRIPATHI",
                "establishment_name": "ABC SOLUTIONS PVT.LTD",
                "member_id": "ABCDE01234567890123456",
                "date_of_joining": "2023-12-04",
                "date_of_exit": "2024-08-31"
            }
        ],
        "employment_history_report": "https://aadhaar-kyc-docs.s3.amazonaws.com/surepass/employment_history_uan/employment_history_uan_v2_report_bbxduPdlQTsqcIjIIIsl/report_1764855502273854.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20251204%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251204T133822Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=af96ab65e0340b9fdfc80c8b13fa1940"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid UAN

Authentication Error

No Records Found

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

This error occurs when the provided UAN number is not in the correct format or does not exist in EPFO records.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure vaults; never hardcode tokens in client-side code

HTTPS Only: Always use HTTPS endpoints to ensure encrypted data transmission

Token Rotation: Implement regular token rotation policies and handle token expiration gracefully

User Consent: Obtain explicit consent from individuals before accessing their employment history data

Data Minimization: Only request and store employment history data when necessary for your business use case

Access Controls: Implement role-based access controls to limit who can access employment verification data

Partner Logo Security: Ensure partner_url points to secure, trusted sources; validate and sanitize logo URLs before submission

User Experience Guidelines

Clear Communication: Inform users why their UAN is needed and how their employment data will be used

Progress Indicators: Display loading indicators while the API request is being processed

Error Messaging: Provide user-friendly error messages that guide users on corrective actions (e.g., "Please verify your UAN number")

PDF Download Option: Offer users the ability to download the employment history PDF report for their records

Data Privacy: Display a privacy notice explaining how employment data is handled and protected

Timeout Handling: Implement appropriate timeout mechanisms and retry logic for failed requests

PDF Expiry Notice: Inform users that the PDF download link expires after 600 seconds (10 minutes) and should be downloaded promptly

Branded Experience: When using partner_url, ensure logo dimensions and quality are optimized for professional PDF presentation

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

This API accesses sensitive personal employment data regulated under various Indian laws. Ensure compliance with the following:

Data Protection: Comply with the Digital Personal Data Protection Act, 2023 (DPDPA) and obtain explicit consent before processing personal data

EPFO Regulations: Use employment data only for legitimate purposes as defined by EPFO guidelines

Purpose Limitation: Utilize employment history data solely for the stated purpose (verification, background checks, etc.)

Data Retention: Implement data retention policies that comply with regulatory requirements; do not store data longer than necessary

User Rights: Provide mechanisms for users to access, correct, and delete their employment data as per data protection regulations

Audit Trail: Maintain logs of all employment data access for compliance audits and regulatory inquiries

Third-Party Sharing: Do not share employment history data with third parties without explicit user consent and legal authorization

PDF Report Security: PDF reports containing sensitive employment data should be handled securely; implement appropriate access controls and encryption

Partner Branding Compliance: When using partner_url for branded reports, ensure compliance with branding guidelines and data processing agreements

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-v2-report' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "123456789012" }'

{ "data": { "client_id": "employment_history_uan_v2_report_bbxduPdlQTsqcI", "uan": "123456789012", "employment_history": [ { "name": "MUNNA TRIPATHI", "guardian_name": "KALEEN TRIPATHI", "establishment_name": "ABC SERVICES PRIVATE LIMITED", "member_id": "FGHIJ01234567890123456", "date_of_joining": "2024-09-01", "date_of_exit": "2025-12-05" }, { "name": "MUNNA TRIPATHI", "guardian_name": "KALEEN TRIPATHI", "establishment_name": "ABC SOLUTIONS PVT.LTD", "member_id": "ABCDE01234567890123456", "date_of_joining": "2023-12-04", "date_of_exit": "2024-08-31" } ], "employment_history_report": "https://aadhaar-kyc-docs.s3.amazonaws.com/surepass/employment_history_uan/employment_history_uan_v2_report_bbxduPdlQTsqcIjIIIsl/report_1764855502273854.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20251204%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251204T133822Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=af96ab65e0340b9fdfc80c8b13fa1940" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Employment History By UAN V2 Report

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