EPFO Latest Employment - UAN

The following document highlights the details of the EPFO Latest Employment - UAN API.

API Description

Objective

The EPFO Latest Employment - UAN API retrieves the latest employment details associated with a user's Universal Account Number(UAN) from the Employees' Provident Fund Organisation (EPFO) records.

Input	Output
UAN and consent	The latest employment details including name, establishment name, member ID, date of joining, and date of exit. The complete list of output fields is available in the Success Response Details section

API URL

https://ind-engine.thomas.hyperverge.co/v1/uanEpfoLatest

API Endpoint

uanEpfoLatest

Overview

The EPFO Latest Employment - UAN API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the EPFO Latest Employment - UAN API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
uanNumber	Mandatory	string	The UAN (Universal Account Number) associated with the EPFO account	Not Applicable	Not Applicable
consent	Mandatory	string	The consent provided by the user for accessing EPFO data	"Y" or "N"	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the EPFO Latest Employment - UAN API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/uanEpfoLatest' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "uanNumber": "<Enter_the_UAN_Number>",
    "consent": "<Enter_Y_or_N>"
}'

Success Responses

The following code snippet demonstrates a success response from the EPFO Latest Employment - UAN API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "message": "Latest employment record fetched.",
    "employmentData": {
      "name": "<Employee_Name>",
      "establishmentName": "<Establishment_Name>",
      "memberId": "<Member_ID>",
      "dateOfJoining": "<Date_Of_Joining>",
      "dateOfExit": "<Date_Of_Exit>"
    }
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the EPFO Latest Employment - UAN API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The status code of the response
result	object	The result object containing the employment data
result.message	string	The message indicating the status of the employment record fetch
result.employmentData	object	The employment details object containing all employment information
result.employmentData.name	string	The full name of the individual
result.employmentData.establishmentName	string	The name of the company or organization where the individual was employed
result.employmentData.memberId	string	The unique identification number assigned to the individual within the organization or employment system
result.employmentData.dateOfJoining	string	The date when the individual started working at the establishment
result.employmentData.dateOfExit	string	The date when the individual ceased employment with the establishment, either through resignation, termination, or any other reason
metaData	object	The metadata object containing request tracking information
metaData.requestId	string	The unique identifier for the request
metaData.transactionId	string	The transaction identifier for tracking

Failure Response

The following code snippet demonstrates a response when no employment records are found:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "message": "No employment records found."
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Responses

The following are some error responses from the EPFO Latest Employment - UAN API:

Invalid UAN Number

{
  "message": "Provide a valid UAN number",
  "statusCode": 400,
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Input Validation Error

{
  "message": "Input Validation Error: is not one of enum values: Y,N",
  "statusCode": 400,
  "status": "failure"
}

No Consent Given

{
  "message": "Please provide consent",
  "statusCode": 400,
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Missing/Invalid Credentials

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure"
}

Internal Server Error

{
  "message": "Internal Server Error",
  "statusCode": 500,
  "status": "failure"
}

Service Unavailable

{
  "message": "Service Unavailable",
  "statusCode": 503,
  "status": "failure"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	Provide a valid UAN number	The request has an invalid UAN number that is empty, invalid, or does not exist	Provide a valid UAN number in the request
400	Input Validation Error: is not one of enum values: Y,N	The request has an invalid consent value that is not one of the allowed enum values	Provide valid consent parameter with value "Y" or "N" in the request
400	Please provide consent	The request is missing the consent parameter or has an invalid consent value	Provide valid consent parameter with value "Y" or "N" in the request
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey credentials in the request
500	Internal Server Error	The request has an internal server error. Please check the request headers or contact the HyperVerge team for investigation	Please check the request headers or contact the HyperVerge team for resolution
503	Service Unavailable	The EPFO service is currently unavailable. Please try again later or contact the HyperVerge team for investigation	Please try again later or contact the HyperVerge team for resolution