Past Employment History - v2

Introduction:

This API is responsible for fetching the EPFO's Past Employment History based on the Universal Account Number (UAN). This paints a vivid and detailed picture of an individual's employment history, offering valuable insights into their professional journey.

Sample cURL:

curl --location 'https:/api-preproduction.signzy.app/api/v3/underwriting/fetch-employment-history-v2' \
--header 'Authorization: <auth-token>' \
--header 'Content-Type: application/json' \
--data '{
    "pan": "",
    "mobile": "",
    "uan": "",
    "dob": "",
    "employeeName": ""
}'

Request Headers:

Key	Value
Authorization	shared by Signzy
Content-type	application/json
x-client-unique-id	Unique id of the client
Content-Length	Specifies the request body size.
Host	Identifies the target server.
User-Agent	Identifies the client making the request.
Accept	Specifies the preferred response content type.
Accept-Encoding	Specifies supported compression formats.
Connection	Determines whether to keep the connection open.

Request Body:

{
    "pan": "ABCDE1234F",
    "mobile": "1234567890",
    "dob": "2000-05-15",
    "employeeName": "Rohit Sharma"
}

PARAMETERS	DESCRIPTION	TYPE	VALUE (COMPULSORY OR OPTIONAL)	SEARCH PARAMETERS DESCRIPTION
uan	UAN stands for Universal Account Number. It is a unique 12-digit identification number assigned to employees contributing to the Employees' Provident Fund (EPF) in India.	String	Conditional Mandatory	UAN should not be passed with any other parameters
pan	Pan number of the individual	String	Conditional Mandatory	Only PAN is a valid input
mobile	Mobile number of the individual	String	Conditional Mandatory	Only mobile is a valid input Optional parameter if pan is provided
dob	Date of Birth of the individual (Format: yyyy-mm-dd)	String	Conditional Mandatory	Optional parameter if pan is provided
employeeName	Name of the employee	String	Conditional Mandatory	PAN is required if employee name is provided

Search Methods:

PAN-based lookup

Lookup is performed using PAN.

Mobile-based lookup

Lookup is performed using mobile number.

Direct UAN lookup

Provided UAN is directly used.

PAN with Mobile fallback

PAN lookup is attempted first.

If UAN is not found, lookup proceeds with Mobile.

Combined lookup using PAN, Mobile, DOB & Employee Name Lookup priority:

Mobile

DOB + Employee Name

Note: If UAN, PAN, mobile number, and date of birth are all provided in the request, the search will be performed using the UAN only. PAN, mobile number, and date of birth will be ignored.

Response Data:

{
    "result": {
        "employmentHistory": [
            {
                "uan": "100123456789",
                "memberId": "ABC1234567890000012345",
                "name": "RAHUL SHARMA",
                "fatherOrHusbandName": "",
                "establishmentId": "ABC123456789000",
                "establishmentName": "XYZ TECHNOLOGIES LTD",
                "dateOfJoining": "2019-06-15",
                "dateOfExit": "2021-03-30",
                "tenureOfEmployment": 21
            },
            {
                "uan": "100123456789",
                "memberId": "DEF9876543210000065432",
                "name": "RAHUL SHARMA",
                "fatherOrHusbandName": "",
                "establishmentId": "DEF987654321000",
                "establishmentName": "ABC CONSULTANCY SERVICES",
                "dateOfJoining": "2017-01-10",
                "dateOfExit": "2019-05-20",
                "tenureOfEmployment": 28
            }
        ],
        "limitedOutput": false,
        "uanDataSource": [
            {
                "uan": "100123456789",
                "source": "pan"
            }
        ],
        "recentEmployerData": {
            "memberId": "ABC1234567890000012345",
            "establishmentId": "ABC123456789000",
            "dateOfExit": "2021-03-30",
            "dateOfJoining": "2019-06-15",
            "establishmentName": "XYZ TECHNOLOGIES LTD",
            "employerConfidenceScore": null
        },
        "uanDetails": [
            {
                "100123456789": {
                    "basicDetails": {
                        "gender": "MALE",
                        "dateOfBirth": "1990-08-25",
                        "employeeConfidenceScore": null,
                        "name": "RAHUL SHARMA",
                        "mobile": "",
                        "aadhaarVerificationStatus": -1
                    },
                    "employmentDetails": {
                        "memberId": "ABC1234567890000012345",
                        "establishmentId": "ABC123456789000",
                        "dateOfExit": "2021-03-30",
                        "dateOfJoining": "2019-06-15",
                        "leaveReason": "",
                        "establishmentName": "XYZ TECHNOLOGIES LTD",
                        "employerConfidenceScore": null
                    }
                }
            }
        ],
        "recentEmploymentSummary": {
            "uan": [
                "100123456789"
            ],
            "summary": {
                "recentEmployerData": {
                    "memberId": "ABC1234567890000012345",
                    "establishmentId": "ABC123456789000",
                    "dateOfExit": "2021-03-30",
                    "dateOfJoining": "2019-06-15",
                    "establishmentName": "XYZ TECHNOLOGIES LTD",
                    "employerConfidenceScore": null,
                    "matchingUan": "100123456789",
                    "epfo": {
                        "isRecent": false,
                        "isNameUnique": false,
                        "hasPfFilingsDetails": true
                    }
                },
                "matchingUan": "100123456789",
                "isEmployed": false,
                "employeeNameMatch": null,
                "employerNameMatch": null,
                "uanCount": 1,
                "dateOfExitMarked": true
            },
            "uanDetails": {
                "100123456789": {
                    "basicDetails": {
                        "gender": "MALE",
                        "dateOfBirth": "1990-08-25",
                        "employeeConfidenceScore": null,
                        "name": "RAHUL SHARMA",
                        "mobile": "",
                        "aadhaarVerificationStatus": 1
                    },
                    "employmentDetails": {
                        "memberId": "ABC1234567890000012345",
                        "establishmentId": "ABC123456789000",
                        "dateOfExit": "2021-03-30",
                        "dateOfJoining": "2019-06-15",
                        "leaveReason": "",
                        "establishmentName": "XYZ TECHNOLOGIES LTD",
                        "employerConfidenceScore": null
                    },
                    "additionalDetails": {
                        "aadhaar": "********5678",
                        "memberId": "ABC1234567890000012345",
                        "email": "R*********[email protected]",
                        "pan": "AB******4P",
                        "bankIfsc": "HDFC*****29",
                        "bankAccNo": "***********9876",
                        "bankAddress": "HDFC BANK, MG ROAD, BANGALORE",
                        "relation": "F",
                        "relativeName": "SURESH SHARMA"
                    }
                }
            },
            "uanSource": [
                {
                    "uan": "100123456789",
                    "source": "pan"
                }
            ],
            "nameDobFilteringScore": null,
            "epfoDetails": {
                "matches": [],
                "pfFilingDetails": [
                    {
                        "totalAmount": 15346789,
                        "employeesCount": 5123,
                        "wageMonth": "DEC-24"
                    },
                    {
                        "totalAmount": 15298765,
                        "employeesCount": 5050,
                        "wageMonth": "NOV-24"
                    },
                    {
                        "totalAmount": 15123456,
                        "employeesCount": 4985,
                        "wageMonth": "OCT-24"
                    }
                ],
                "establishmentInfo": {
                    "establishmentId": "ABC123456789000",
                    "establishmentName": "XYZ TECHNOLOGIES LTD",
                    "dateOfSetup": "2010-05-12",
                    "ownershipType": "Private Limited Company"
                }
            }
        }
    }
}

PARAMETERS	DESCRIPTION	TYPE
result	The main object containing details about employment history, UAN data, recent employer data, and additional employment-related information.	Object
result.employmentHistory	A list of past employment records associated with the individual. Each entry contains details such as UAN, employer details, joining and exit dates, and tenure.	List[Object]
result.employmentHistory[].uan	The Universal Account Number (UAN) linked to the employment record.	String
result.employmentHistory[].memberId	A unique identifier assigned to the employee by the employer.	String
result.employmentHistory[].name	The name of the individual.	String
result.employmentHistory[].fatherOrHusbandName	The name of the individual's father or husband. This field may be empty.	String
result.employmentHistory[].establishmentId	A unique identifier assigned to the employer's establishment.	String
result.employmentHistory[].establishmentName	The name of the employer's establishment.	String
result.employmentHistory[].dateOfJoining	The date when the employee joined the establishment. Format: "YYYY-MM-DD"	String
result.employmentHistory[].dateOfExit	The date when the employee left the establishment. Format: "YYYY-MM-DD"	String
result.employmentHistory[].tenureOfEmployment	The duration (in months) of employment at the establishment.	Number
result.limitedOutput	ndicates whether the output is limited (true) or complete (false).	Boolean
result.uanDataSource	A list of data sources used to retrieve the UAN information.	List[Object]
result.uanDataSource[].uan	The Universal Account Number (UAN) retrieved from the specified source.	String
result.uanDataSource[].source	The source from which the UAN information was derived (e.g., "pan").	String
result.recentEmployerData	Contains details about the most recent employer.	Object
result.recentEmployerData.memberId	The membership ID of the employee under the most recent employer.	String
result.recentEmployerData.establishmentId	The unique identifier of the most recent establishment.	String
result.recentEmployerData.dateOfExit	The exit date from the most recent establishment. Format: "YYYY-MM-DD"	String
result.recentEmployerData.dateOfJoining	The joining date for the most recent establishment. Format: "YYYY-MM-DD"	String
result.recentEmployerData.establishmentName	The name of the most recent employer.	String
result.recentEmployerData.employerConfidenceScore	A confidence score indicating the reliability of the employer’s information. (May be null)	String
result.uanDetails	An array containing detailed UAN information, including basic and employment details.	Array
result.uanDetails[].basicDetails	An object containing basic details about the individual.	Object
result.uanDetails[].basicDetails.gender	The gender of the individual.	String
result.uanDetails[].basicDetails.dateOfBirth	The date of birth of the individual. Format: "YYYY-MM-DD"	String
result.uanDetails[].basicDetails.employeeConfidenceScore	A confidence score for the employee’s details. (May be null)	String
result.uanDetails[].basicDetails.name	The full name of the employee.	String
result.uanDetails[].basicDetails.mobile	The mobile number associated with the UAN. (May be empty)	String
result.uanDetails[].basicDetails.aadhaarVerificationStatus	This field is deprecated.	Number
result.uanDetails[].employmentDetails	Contains employment-related details.	Object
result.uanDetails[].employmentDetails.memberId	The unique membership ID of the employee.	String
result.uanDetails[].employmentDetails.establishmentId	The unique establishment ID where the employee worked.	String
result.uanDetails[].employmentDetails.dateOfExit	The date when the employee left the job. Format: "YYYY-MM-DD"	String
result.uanDetails[].employmentDetails.dateOfJoining	The date when the employee joined the job. Format: "YYYY-MM-DD"	String
result.uanDetails[].employmentDetails.leaveReason	The reason for leaving the job. (May be empty)	String
result.uanDetails[].employmentDetails.establishmentName	The name of the employer’s establishment.	String
result.uanDetails[].employmentDetails.employerConfidenceScore	A confidence score for employer details. (May be null)	String
result.recentEmploymentSummary	Contains a summary of the individual's most recent employment details, including UAN data, employer information, and EPFO filings.	Object
result.recentEmploymentSummary.uan	A list containing the UAN(s) linked to recent employment.	List[String]
result.recentEmploymentSummary.summary	Summarizes details about the most recent employer and employment status.	Object
result.recentEmploymentSummary.summary.recentEmployerData	Contains details about the most recent employer the individual worked for.	Object
result.recentEmploymentSummary.summary.recentEmployerData.memberId	The unique membership ID of the employee at the most recent employer.	String
result.recentEmploymentSummary.summary.recentEmployerData.establishmentId	The establishment ID of the most recent employer.	String
result.recentEmploymentSummary.summary.recentEmployerData.dateOfExit	The exit date from the most recent employer. Format: "YYYY-MM-DD"	String
result.recentEmploymentSummary.summary.recentEmployerData.dateOfJoining	The joining date for the most recent employer. Format: "YYYY-MM-DD"	String
result.recentEmploymentSummary.summary.recentEmployerData.establishmentName	The name of the most recent employer.	String
result.recentEmploymentSummary.summary.recentEmployerData.employerConfidenceScore	A confidence score that evaluates the accuracy of the employer's details. (May be null)	Number
result.recentEmploymentSummary.summary.recentEmployerData.matchingUan	The UAN associated with this employment record.	String
result.recentEmploymentSummary.summary.recentEmployerData.epfo	Contains details about the employer’s EPFO (Employee Provident Fund Organization) filings.	Object
result.recentEmploymentSummary.summary.recentEmployerData.epfo.isRecent	Indicates whether the employer’s EPFO details are recent.	Boolean
result.recentEmploymentSummary.summary.recentEmployerData.epfo.isNameUnique	ndicates whether the establishment name is unique in the EPFO database.	Boolean
result.recentEmploymentSummary.summary.recentEmployerData.epfo.hasPfFilingsDetails	Indicates whether the employer has filed Provident Fund (PF) contributions.	Boolean
result.recentEmploymentSummary.summary.matchingUan	The UAN associated with the most recent employment.	String
result.recentEmploymentSummary.summary.isEmployed	Indicates whether the individual is currently employed.	Boolean
result.recentEmploymentSummary.summary.employeeNameMatch	Indicates if the employee’s name matches records. (May be null)	Boolean
result.recentEmploymentSummary.summary.employerNameMatch	Indicates if the employer’s name matches records. (May be null)	Boolean
result.recentEmploymentSummary.summary.uanCount	The total number of UANs associated with the individual.	Number
result.recentEmploymentSummary.summary.dateOfExitMarked	Indicates whether the exit date is recorded in the system.	Boolean
result.recentEmploymentSummary.uanDetails	Contains detailed information about the UAN, including basic details, employment records, and additional details.	Object
result.recentEmploymentSummary.uanDetails[UAN]	An object where the UAN acts as a key, containing associated details.	Object
result.recentEmploymentSummary.uanDetails[UAN].basicDetails	Contains basic personal details of the individual.	Object
result.recentEmploymentSummary.uanDetails[UAN].basicDetails.gender	Gender of the individual	String
result.recentEmploymentSummary.uanDetails[UAN].basicDetails.dateOfBirth	Date of Birth of the individual. Format: yyyy-mm-dd	String
result.recentEmploymentSummary.uanDetails[UAN].basicDetails.employeeConfidenceScore	Confidence score of the employee	Number
result.recentEmploymentSummary.uanDetails[UAN].basicDetails.name	Name of the employee	String
result.recentEmploymentSummary.uanDetails[UAN].basicDetails.mobile	Mobile number of the employee	String
result.recentEmploymentSummary.uanDetails[UAN].basicDetails.aadhaarVerificationStatus	This field is deprecated	Number
result.recentEmploymentSummary.uanDetails[UAN].employmentDetails	Contains employment-related information.	Object
result.recentEmploymentSummary.uanDetails[UAN].employmentDetails.memberId	Unique membership ID.	String
result.recentEmploymentSummary.uanDetails[UAN].employmentDetails.establishmentId	Employer's establishment ID.	String
result.recentEmploymentSummary.uanDetails[UAN].employmentDetails.dateOfExit	Last working date ("YYYY-MM-DD").	String
result.recentEmploymentSummary.uanDetails[UAN].employmentDetails.dateOfJoining	Joining date ("YYYY-MM-DD").	String
result.recentEmploymentSummary.uanDetails[UAN].employmentDetails.leaveReason	Reason for leaving (may be empty).	String
result.recentEmploymentSummary.uanDetails[UAN].employmentDetails.establishmentName	Name of the employer.	String
result.recentEmploymentSummary.uanDetails[UAN].employmentDetails.employerConfidenceScore	Confidence score for employer details.	Number
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails	Contains additional information related to the individual.	Object
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails.aadhaar	this field is deprecated	String
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails.memberId	Unique membership ID.	String
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails.email	Partially masked email.	String
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails.pan	Partially masked PAN number.	String
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails.bankIfsc	Partially masked bank IFSC code.	String
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails.bankAccNo	Partially masked bank account number.	String
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails.bankAddress	Bank branch address.	String
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails.relation	Relationship with the nominee (e.g., "F" for Father).	String
result.recentEmploymentSummary.uanDetails[UAN].additionalDetails.relativeName	Name of the nominee/relative.	String
result.recentEmploymentSummary.uanSource	A list of sources from which the UAN data was retrieved.	List[Object]
result.recentEmploymentSummary.uanSource[].uan	The Universal Account Number (UAN) retrieved.	String
result.recentEmploymentSummary.uanSource[].source	The source from which the UAN was retrieved (e.g., "pan").	String
result.recentEmploymentSummary.nameDobFilteringScore	A score for filtering based on name and date of birth. (May be null)	Number
result.recentEmploymentSummary.epfoDetails	Contains Employee Provident Fund (EPFO) details, including filing information and establishment details.	Object
result.recentEmploymentSummary.epfoDetails.pfFilingDetails	A list of Provident Fund (PF) filings made by the employer.	List[Object]
result.recentEmploymentSummary.epfoDetails.pfFilingDetails[].totalAmount	The total PF amount filed.	Number
result.recentEmploymentSummary.epfoDetails.pfFilingDetails[].employeesCount	The number of employees covered in the PF filing.	Number
result.recentEmploymentSummary.epfoDetails.pfFilingDetails[].wageMonth	The wage month for which PF was filed. Format: "MMM-YY"	String
result.recentEmploymentSummary.epfoDetails.establishmentInfo	Contains details about the employer's establishment.	Object
result.recentEmploymentSummary.epfoDetails.establishmentInfo.establishmentId	Employer’s establishment ID.	String
result.recentEmploymentSummary.epfoDetails.establishmentInfo.establishmentName	Employer’s name.	String
result.recentEmploymentSummary.epfoDetails.establishmentInfo.dateOfSetup	Employer’s setup date ("YYYY-MM-DD").	String
result.recentEmploymentSummary.epfoDetails.establishmentInfo.ownershipType	The ownership type (e.g., "Public Ltd Company").	String

Response Headers:

PARAMETERS	TYPE	DESCRIPTION
x-signzy-trace-id	String	A unique identifier generated by Signzy to track and debug API requests within their system.
x-trace-id	String	A globally unique trace ID used for end-to-end tracking of API requests across multiple services.
Date	String	Specifies the date and time when the response was generated by the server, in GMT (Greenwich Mean Time).
Content-Type	String	Defines the type of content returned by the API. Here, it indicates that the response body is in JSON format with UTF-8 character encoding.
Transfer-Encoding	String	The response is sent in chunks instead of a single block. This is useful for streaming large responses.
Connection	String	Specifies whether the connection should be kept open for further requests (keep-alive) or closed after the response.
Vary	String	Indicates which request headers influence the response. Helps in caching.
Access-Control-Allow-Origin	String	Allows cross-origin requests from any domain (* means any origin is allowed).
Cache-Control	String	Controls caching behavior.
Pragma	String	Another way to prevent caching (older HTTP/1.0 compatibility).
Strict-Transport-Security (HSTS)	String	Enforces secure HTTPS connections.
X-XSS-Protection	String	Protects against Cross-Site Scripting (XSS) attacks.
X-Content-Type-Options	String	Prevents browsers from MIME-sniffing the content type, ensuring it is strictly interpreted as declared.
Access-Control-Allow-Credentials	Boolean	Allows the browser to send cookies and authentication headers in cross-origin requests.
Access-Control-Allow-Headers	String	Lists the allowed headers in cross-origin requests.
Access-Control-Allow-Methods	String	Specifies which HTTP methods are allowed for cross-origin requests.
Content-Encoding	String	Specifies the encoding used to compress the response body.
X-Kong-Upstream-Latency	String	Time (in milliseconds) taken by the upstream server to process the request.
X-Kong-Proxy-Latency	String	Time (in milliseconds) taken by the Kong API Gateway to process the request.
Via	String	Shows that the response was routed through Kong API Gateway, version 3.4.2.

Sample Status Codes and Messages:

{
    "error": {
        "reason": "ERROR",
        "status": 500,
        "message": "Internal Server Error",
        "type": "Internal Server Error",
        "statusCode": 500,
        "name": "error"
    }
}