Employment History PAN Mobile

Endpoint Overview

POST /api/v1/employment/employment-history-pan-mobile

Description

This API retrieves comprehensive employment history details for a user based on their PAN number or mobile number. It provides valuable information including EPFO (Employees' Provident Fund Organisation) details, month-wise contribution history, and detailed employment records. The API helps verify employment claims, assess employment stability, and validate work experience by accessing official EPFO records.

Key Benefits

Verify employment history using official EPFO records

Access detailed employment timeline with joining and exit dates

Track PF contribution history on a month-by-month basis

Validate employer information with establishment details

Use Cases

Financial Services

HR & Recruitment

Insurance

Verify employment stability for loan and credit applications

Validate income sources during credit underwriting

Confirm employment tenure for premium financial products

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)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
pan_number	String	Conditional*	User's PAN number
mobile_number	String	Conditional*	User's mobile number
employee_name	String	No	Name of the employee
employer_name	String	No	Name of the employer

*Either pan_number or mobile_number is required.

Example Request

{
    "mobile_number": "8079027839",
    "employee_name": "VISHAL",
    "employer_name": "VISHAL"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all employment history data
data.client_id	String	Unique client identifier for the request
data.uan	String	Universal Account Number of the employee
data.epfo_details	Object	EPFO-related details of the employee
data.month_history	Array	List of contribution status for each month
data.employment_history_details	Array	Detailed history of employment records
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Additional message (null if successful)
message_code	String	Code indicating the status of the request

EPFO Details Object

Parameter	Type	Description
employee_name_matching_score	String	Matching score of the employee's name
employer_name_matching_score	String	Matching score of the employer's name
establishment_name	String	Name of the establishment linked with EPFO
establishment_info	Object	Additional details of the establishment

Establishment Info Object

Parameter	Type	Description
address	String	Address of the establishment
city	String	City where the establishment is located
district	String	District where the establishment is located
state	String	State where the establishment is located
region	String	Region code of the establishment
establishment_id	String	Establishment ID of the employer
less_info	Boolean	Indicates whether fewer details are available

Month History Object

Parameter	Type	Description
month_year	String	Month and year of contribution (e.g., "NOV-24")
status	Boolean	Indicates whether the contribution was made for that month

Employment History Details Object

Parameter	Type	Description
name	String	Name of the employee
guardian_name	String	Guardian name of the employee
establishment_name	String	Name of the establishment
member_id	String	Member ID linked to the EPFO account
date_of_joining	Date	Date when the employee joined (YYYY-MM-DD)
date_of_exit	Date	Date when the employee left (null if still employed)
last_pf_submitted	Date	Date of the last PF submission (YYYY-MM-DD)
wage_month	String	Month for which wages were submitted (e.g., "Oct-2024")

Example Successful Response

{
    "data": {
        "client_id": "employment_history_pan_mobile_ROomlsLyTpPrRGAZebAl",
        "uan": "109804431233",
        "epfo_details": {
            "employee_name_matching_score": "62",
            "employer_name_matching_score": "38",
            "establishment_name": "TRIDENT LIMITED",
            "establishment_info": {
                "address": "HOSHANGABAD ROAD BUDHNI MADHYA PRADESH",
                "city": "BUDHNI",
                "establishment_name": "TRIDENT LIMITED",
                "district": "BUDHNI",
                "state": "MADHYA PRADESH",
                "region": "MP",
                "establishment_id": "MPBPL2788671000",
                "less_info": false
            }
        },
        "month_history": [
            {
                "month_year": "NOV-24",
                "status": true
            },
            {
                "month_year": "OCT-24",
                "status": true
            },
            {
                "month_year": "SEP-24",
                "status": true
            }
        ],
        "employment_history_details": [
            {
                "name": "AJAY SINGH",
                "guardian_name": "GOPAL SINGH",
                "establishment_name": "TRIDENT LIMITED (BED LINEN DIVISION)",
                "member_id": "MPBPL27886730000017755",
                "date_of_joining": "2023-01-05",
                "date_of_exit": null,
                "last_pf_submitted": "2024-11-14",
                "wage_month": "Oct-2024"
            },
            {
                "name": "AJAY SINGH",
                "guardian_name": "GOPAL SINGH",
                "establishment_name": "TRIDENT LIMITED (BED LINEN DIVISION)",
                "member_id": "MPBPL27886730000011234",
                "date_of_joining": "2022-10-01",
                "date_of_exit": null,
                "last_pf_submitted": "2023-02-15",
                "wage_month": "Jan-2023"
            },
            {
                "name": "AJAY SINGH",
                "guardian_name": "GOPAL SINGH",
                "establishment_name": "TRIDENT LIMITED",
                "member_id": "MPBPL00188730000039854",
                "date_of_joining": "2021-11-02",
                "date_of_exit": null,
                "last_pf_submitted": "2022-10-14",
                "wage_month": "Sep-2022"
            },
            {
                "name": "AJAY SINGH",
                "guardian_name": "GOPAL SINGH",
                "establishment_name": "TRIDENT LIMITED",
                "member_id": "MPBPL00188730000030099",
                "date_of_joining": "2021-08-18",
                "date_of_exit": null,
                "last_pf_submitted": "2021-11-13",
                "wage_month": "Oct-2021"
            },
            {
                "name": "AJAY SINGH",
                "guardian_name": "GOPAL SINGH",
                "establishment_name": "TANU ENTERPRISES",
                "member_id": "MPBPL14438410000011534",
                "date_of_joining": "2020-08-10",
                "date_of_exit": null,
                "last_pf_submitted": "2021-02-15",
                "wage_month": "Jan-2021"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Missing Required Fields

Record Not Found

{
    "status_code": 401,
    "success": false,
    "message": "Invalid or expired token",
    "message_code": "authentication_error"
}

This error occurs when the JWT token is invalid, expired, or missing.

Integration Best Practices

Security Recommendations

Store API credentials 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

Rotate JWT tokens periodically and implement token expiration

User Experience Guidelines

Implement proper loading states while waiting for API response

Display employment history in chronological order for better readability

Highlight gaps in employment history for easier analysis

Provide clear explanations for matching scores to help users interpret results

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API: Verify PAN card details of individuals

UAN Verification API: Verify Universal Account Number details

Employment Verification API: Verify current employment status

Income Verification API: Verify income details from various sources

Compliance and Legal Considerations

This API accesses EPFO data which contains personally identifiable information (PII). Ensure you have proper consent from users before accessing their employment history. Usage of this data must comply with relevant 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 specific purpose for which consent was obtained.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/employment/employment-history-pan-mobile' \ --header 'Content-Type: application/json' \ --data-raw '{ "mobile_number": "8079027839", "employee_name": "VISHAL", "employer_name": "VISHAL" }'

{ "data": { "client_id": "employment_history_pan_mobile_ROomlsLyTpPrRGAZebAl", "uan": "109804431233", "epfo_details": { "employee_name_matching_score": "62", "employer_name_matching_score": "38", "establishment_name": "TRIDENT LIMITED", "establishment_info": { "address": "HOSHANGABAD ROAD BUDHNI MADHYA PRADESH", "city": "BUDHNI", "establishment_name": "TRIDENT LIMITED", "district": "BUDHNI", "state": "MADHYA PRADESH", "region": "MP", "establishment_id": "MPBPL2788671000", "less_info": false } }, "month_history": [ { "month_year": "NOV-24", "status": true }, { "month_year": "OCT-24", "status": true }, { "month_year": "SEP-24", "status": true } ], "employment_history_details": [ { "name": "AJAY SINGH", "guardian_name": "GOPAL SINGH", "establishment_name": "TRIDENT LIMITED (BED LINEN DIVISION)", "member_id": "MPBPL27886730000017755", "date_of_joining": "2023-01-05", "date_of_exit": null, "last_pf_submitted": "2024-11-14", "wage_month": "Oct-2024" }, { "name": "AJAY SINGH", "guardian_name": "GOPAL SINGH", "establishment_name": "TRIDENT LIMITED (BED LINEN DIVISION)", "member_id": "MPBPL27886730000011234", "date_of_joining": "2022-10-01", "date_of_exit": null, "last_pf_submitted": "2023-02-15", "wage_month": "Jan-2023" }, { "name": "AJAY SINGH", "guardian_name": "GOPAL SINGH", "establishment_name": "TRIDENT LIMITED", "member_id": "MPBPL00188730000039854", "date_of_joining": "2021-11-02", "date_of_exit": null, "last_pf_submitted": "2022-10-14", "wage_month": "Sep-2022" }, { "name": "AJAY SINGH", "guardian_name": "GOPAL SINGH", "establishment_name": "TRIDENT LIMITED", "member_id": "MPBPL00188730000030099", "date_of_joining": "2021-08-18", "date_of_exit": null, "last_pf_submitted": "2021-11-13", "wage_month": "Oct-2021" }, { "name": "AJAY SINGH", "guardian_name": "GOPAL SINGH", "establishment_name": "TANU ENTERPRISES", "member_id": "MPBPL14438410000011534", "date_of_joining": "2020-08-10", "date_of_exit": null, "last_pf_submitted": "2021-02-15", "wage_month": "Jan-2021" } ] }, "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 ********************

Employment History PAN Mobile

Employment History PAN Mobile#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

EPFO Details Object#

Establishment Info Object#

Month History Object#

Employment History Details Object#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Employment History PAN Mobile

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

EPFO Details Object

Establishment Info Object

Month History Object

Employment History Details Object

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples