Employment History by UAN V2

Endpoint Overview

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

Description

The Employment History by UAN V2 API enables you to retrieve a comprehensive employment history for an individual using their Universal Account Number (UAN). This API is designed to streamline background verification, financial onboarding, and compliance processes by providing verified employment records directly from authoritative sources.

This endpoint returns detailed employment information, including employee name, guardian name, establishment name, member ID, date of joining, and date of exit for each employment record associated with the provided UAN.

Key Benefits

Automates employment verification, reducing manual effort and turnaround time.

Provides reliable, up-to-date employment data for compliance and risk assessment.

Enhances onboarding and KYC processes with verified employment history.

Supports seamless integration into HR, BFSI, and background verification workflows.

Use Cases

Banking & Financial Services

Human Resources

Fintech & Lending

Automate loan eligibility checks by verifying applicant employment history.

Streamline KYC and onboarding for new account holders.

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	Bearer token (JWT) for API authentication
Content-Type	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
id_number	string	Yes	Universal Account Number (UAN)

Example Request

{
  "id_number": "101234567890"
}

Process Response

Response Parameters

Certainly! Here’s your response parameters table rewritten to use dot notation for all nested fields:

Parameter	Type	Description
data	object	Contains the main response data
data.client_id	string	Unique request identifier
data.uan	string	The UAN provided in the request
data.employment_history	array	List of employment records
data.employment_history[].name	string	Employee's full name
data.employment_history[].guardian_name	string	Name of the employee's guardian
data.employment_history[].establishment_name	string	Name of the employing organization
data.employment_history[].member_id	string	Unique member ID for the employment record
data.employment_history[].date_of_joining	string	Date of joining (YYYY-MM-DD)
data.employment_history[].date_of_exit	string	Date of exit (YYYY-MM-DD)
status_code	number	HTTP status code (e.g., 200 for success)
success	boolean	Indicates if the request was successful
message	string	Human-readable status message
message_code	string	Machine-readable status code

Example Successful Response

{
  "data": {
    "client_id": "employment_history_uan_v2_AbcXyz123PqrLMN789",
    "uan": "101234567890",
    "employment_history": [
      {
        "name": "RAHUL KUMAR SHARMA",
        "guardian_name": "MOHAN LAL SHARMA",
        "establishment_name": "DELHI METRO RAIL CORPORATION",
        "member_id": "DLCPM00567890000001234",
        "date_of_joining": "2015-06-01",
        "date_of_exit": "2020-03-31"
      }
    ]
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid UAN

Authentication Error

{
    "status_code": 422,
    "success": false,
    "message": "Verification Failed.",
    "message_code": "verification_failed"
}

The provided UAN is invalid or not found in the records.

Integration Best Practices

Security Recommendations

Always use HTTPS to encrypt API requests and responses.

Store your API keys and JWT tokens securely; never expose them in client-side code.

Rotate your API credentials periodically and monitor for unauthorized access.

User Experience Guidelines

Validate UAN format on the client side before making API requests.

Display clear error messages to users in case of invalid input or failed verification.

Code Samples

cURL

Python

Node.js

Related APIs

UAN KYC Verification API: Verifies the KYC status of a UAN.

EPFO Member Passbook API: Retrieves passbook details for a given UAN.

PAN Employment History API: Fetches employment history using PAN as identifier.

Compliance and Legal Considerations

Ensure you have obtained user consent before accessing or processing employment history data. All data usage must comply with applicable data protection and privacy regulations, such as the IT Act, 2000 and relevant RBI/SEBI guidelines.

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

{ "data": { "client_id": "employment_history_uan_v2_AbcXyz123PqrLMN789", "uan": "101234567890", "employment_history": [ { "name": "RAHUL KUMAR SHARMA", "guardian_name": "MOHAN LAL SHARMA", "establishment_name": "DELHI METRO RAIL CORPORATION", "member_id": "DLCPM00567890000001234", "date_of_joining": "2015-06-01", "date_of_exit": "2020-03-31" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Employment History By UAN V2

Employment History by UAN V2#

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