Current Employment Details

Endpoint Overview

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

Description

This API retrieves the current employment details of an individual by using their PAN number, mobile number, or UAN (Universal Account Number). It provides comprehensive information about an individual's employment status, including EPFO (Employees' Provident Fund Organisation) details, employment history, and establishment information.

Key Benefits

Verify employment status using multiple identification methods (PAN, mobile, or UAN)

Access detailed employment history including joining and exit dates

Retrieve comprehensive establishment information including address and location details

Validate employee and employer information with matching scores

Use Cases

Financial Services

HR & Recruitment

Insurance

Verify employment status during loan application processing

Confirm employment details for credit risk assessment

Validate income sources for mortgage applications

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
mobile_number	String	Conditional*	Mobile number of the individual
pan_number	String	Conditional*	PAN number of the individual
uan_number	String	Conditional*	UAN (Universal Account Number) of the individual
employer_name	String	No	Name of the employer for additional verification
employee_name	String	No	Name of the employee for additional verification

*At least one of these parameters (mobile_number, pan_number, or uan_number) is required.

Example Request

{
    "uan_number": "101669824011"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all the employment-related information
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

Data Object

Parameter	Type	Description
client_id	String	Unique identifier for the client
uan	String	UAN number of the individual
month_history	Array of Objects	Monthly employment status history
employment_details	Object	Detailed employment information
epfo_details	Object	EPFO-related information

month_history Object

Parameter	Type	Description
month_year	String	Month and year of the employment status (e.g., "MAY-21")
status	Boolean	Employment status for that month (true = employed)

employment_details Object

Parameter	Type	Description
member_id	String	Member ID associated with EPFO
doe_epf	String	Date of exit from EPF (format: YYYY-MM-DD)
leave_reason	String	Reason for leaving employment
doj_epf	String	Date of joining EPF (format: YYYY-MM-DD)
name	String	Name of the individual
company_name	String	Name of the company where the individual was employed

epfo_details Object

Parameter	Type	Description
employee_name_matching_score	String	Score indicating how well the provided employee name matches records
employer_name_matching_score	String	Score indicating how well the provided employer name matches records
establishment_id	String	Unique identifier for the establishment
establishment_name	String	Name of the establishment
establishment_info	Object	Detailed information about the establishment

establishment_info Object

Parameter	Type	Description
address	String	Complete address of the establishment
city	String	City where the establishment is located
establishment_name	String	Name of the establishment
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	Unique identifier for the establishment
less_info	Boolean	Indicates if limited information is available

Example Successful Response

{
    "data": {
        "client_id": "current_employment_pan_mobile_ptDZogxvvsFxdSwNaujo",
        "uan": "101559824010",
        "employment_details": {
            "member_id": "KDMAL00178080000313123",
            "doe_epf": "2021-05-17",
            "leave_reason": "CESSATION (SHORT SERVICE) - Any other reason",
            "doj_epf": "2021-05-17",
            "name": "VISHAL SINGH RATHORE",
            "company_name": "I PROCESS SERVICES (INDIA) PVT. LTD."
        },
        "month_history": [
            {
                "month_year": "MAY-21",
                "status": true
            }
        ],
        "epfo_details": {
            "employee_name_matching_score": "0",
            "employer_name_matching_score": "0",
            "establishment_id": "KDMAL0017808000",
            "establishment_name": "I PROCESS SERVICES (INDIA) PVT. LTD.",
            "establishment_info": {
                "address": "UNIT NO 602, 6TH FLOOR CENTRE POINT J B NAGAR ANDHERI EAST MUMBAI ANDHERI KURLA ROAD ANDHERI EAST MAHARASHTRA",
                "city": "ANDHERI KURLA ROAD ANDHERI EAST",
                "establishment_name": "I PROCESS SERVICES (INDIA) PVT. LTD.",
                "district": "ANDHERI KURLA ROAD ANDHERI EAST",
                "state": "MAHARASHTRA",
                "region": "KD",
                "establishment_id": "KDMAL0017808000",
                "less_info": false
            }
        }
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid Input

Not Found

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Please provide at least one of mobile_number, pan_number, or uan_number",
    "message_code": "invalid_input"
}

This error occurs when none of the required identification parameters (mobile_number, pan_number, or uan_number) are provided.

Integration Best Practices

Security Recommendations

Store API keys and tokens securely, 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

Implement rate limiting in your application to prevent abuse

User Experience Guidelines

Provide clear feedback to users when employment verification is in progress

Display appropriate error messages when verification fails

Implement retry mechanisms for temporary failures

Cache results when appropriate to improve response times

Code Samples

cURL

Python

Node.js

Related APIs

Employment History API - Retrieves detailed employment history for an individual

EPFO Verification API - Verifies EPFO membership details

UAN Verification API - Validates UAN number and retrieves associated information

Compliance and Legal Considerations

When using this API, ensure compliance with data privacy regulations such as GDPR and India's Personal Data Protection Bill. Only use this API for legitimate verification purposes with proper consent from the individual. Employment data is sensitive personal information and should be handled securely with appropriate access controls.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/employment/current-employment-pan-mobile' \ --header 'Content-Type: application/json' \ --data-raw '{ "uan_number": "101669824011" }'

{ "data": { "client_id": "current_employment_pan_mobile_ptDZogxvvsFxdSwNaujo", "uan": "101559824010", "employment_details": { "member_id": "KDMAL00178080000313123", "doe_epf": "2021-05-17", "leave_reason": "CESSATION (SHORT SERVICE) - Any other reason", "doj_epf": "2021-05-17", "name": "VISHAL SINGH RATHORE", "company_name": "I PROCESS SERVICES (INDIA) PVT. LTD." }, "month_history": [ { "month_year": "MAY-21", "status": true } ], "epfo_details": { "employee_name_matching_score": "0", "employer_name_matching_score": "0", "establishment_id": "KDMAL0017808000", "establishment_name": "I PROCESS SERVICES (INDIA) PVT. LTD.", "establishment_info": { "address": "UNIT NO 602, 6TH FLOOR CENTRE POINT J B NAGAR ANDHERI EAST MUMBAI ANDHERI KURLA ROAD ANDHERI EAST MAHARASHTRA", "city": "ANDHERI KURLA ROAD ANDHERI EAST", "establishment_name": "I PROCESS SERVICES (INDIA) PVT. LTD.", "district": "ANDHERI KURLA ROAD ANDHERI EAST", "state": "MAHARASHTRA", "region": "KD", "establishment_id": "KDMAL0017808000", "less_info": false } } }, "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 ********************

Current Employment Details

Current Employment Details#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Data Object#

month_history Object#

employment_details Object#

epfo_details Object#

establishment_info Object#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Current Employment Details

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Data Object

month_history Object

employment_details Object

epfo_details Object

establishment_info Object

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples