EPFO Employment History - OTP

API Description

Objective

The EPFO Employment History - OTP retrieves the employment details of a user via the mobile number linked to their Universal Account Number (UAN). This API requires a one-time password (OTP) to verify the user's identity.

The verification process involves the following two APIs:

1. Initiate OTP - This is the prerequisite API that initiates an OTP on the user's mobile number to verify their identity. It provides a unique request ID in the response that serves as an input for the following API.

2. Employment Details - This is the API that verifies the OTP and retrieves the user's employment details upon successful verification.

API URLs

The URLs for both the APIs are as follows:

1. Initiate OTP Endpoint

You can use the following endpoint to initiate the OTP generation.

https://ind.thomas.hyperverge.co/v1/epfoSendOtp

2. Employment Details

You can use the following endpoint to retrieve the user's employment information.

https://ind.thomas.hyperverge.co/v1/epfoOtpFlow

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

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

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Accepted Values
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	Application ID shared by HyperVerge	N/A. This is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge	N/A. This is a unique value.
transactionId	Mandatory	Unique ID for the customer journey.	N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Input

The following table provides the complete information on the parameters used in the request body for the API calls.

1. Initiate OTP - Input Parameters

Parameter	Mandatory or Optional	Allowed Values	Default Value	Description
mobile	Mandatory	Not Applicable	Not Applicable	The ten-digit phone number linked with the user's UAN.

2. Employment Details - Input Parameters

Parameter	Mandatory or Optional	Allowed Values	Default Value	Description
requestId	Mandatory	Not Applicable	Not Applicable	The unique identifier for the verification request provided in the response of the Initiate OTP API.

Request

The following section shows the standard curl requests for both the APIs:

1. Initiate OTP - Request

curl --location --request POST 'https://ind.thomas.hyperverge.co/v1/epfoSendOtp' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "mobile": "<Enter_the_Mobile_Number>"
}'

2. Employment Details - Request

curl --location --request POST 'https://ind.thomas.hyperverge.co/v1/epfoOtpFlow' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "requestId": "<Enter_the_Request_ID>",
    "otp": "<Enter_the_OTP_Received>"
}'

Success Responses

The success response samples for both the APIs are as follows:

1. Initiate OTP - Response

The following is a sample response for the Initiate OTP API.

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "requestId": "<Request_ID>"
    }
}

2. Employment Details - Response

The following is a sample response for the Employment Details API.

caution

The response has placeholders instead of the actual values for the user's personally identifiable information.

{
  "status": "success",
  "statusCode": 200,
  "result": {
      "requestId": "<Request_ID>",
      "passbookRequestId": "<Passbook_Request_ID>",
      "fullName": "<The_Full_Name_of_The_User>",
      "fatherName": "<Father's_Name>",
      "dob": "<Date_of_Birth>",
      "companies": {
          "<PF_Number_from_Company_1>": {
              "pfNumber": "<PF_Number_from_Company_1>",
              "companyName": "<Company_Name_1>",
              "establishmentId": "<Establishment_ID_1>",
              "dateOfJoining": "<Date_of_Joining_the_Company>"
          },
          "<PF_Number_from_Company_2>": {
              "pfNumber": "<PF_Number_from_Company_2>",
              "companyName": "<Company_Name_2>",
              "establishmentId": "<Establishment_ID_2>",
               "dateOfJoining": "<Date_of_Joining_the_Company>"
          },
          "<PF_Number_from_Company_3>": {
              "pfNumber": "<PF_Number_from_Company_3>",
              "companyName": "<Company_Name_3>",
              "establishmentId": "<Establishment_ID_3>",
               "dateOfJoining": "<Date_of_Joining_the_Company>"
          },
          "<PF_Number_from_Company_4>": {
              "pfNumber": "<PF_Number_from_Company_4>",
              "companyName": "<Company_Name_4>",
              "establishmentId": "<Establishment_ID_4>",
               "dateOfJoining": "<Date_of_Joining_the_Company>"
          }
      },
      "currentCompanyName": "<Name_of_Current_Company>", 
    "currentEstablishmentId": "<Establishment_Id_for_Current_Company>", 
    "uan": "<UAN>"
  }
}

Failure Response

The following is a sample response for no records found against the mobile number input.

{
  "statusCode": 400,
  "status": "failure",
  "error": "No Records Found",
  "metaData": {
      "requestId": "<Request_ID>"
  }
}

Error Responses

The following are the sample error responses for the API.

Input Validation Error

The following is a sample response for a request missing the transactionId.

{
  "message": "Input Validation Error: does not meet minimum length of 10",
  "statusCode": 400,
  "status": "failure"
}

Missing/Invalid Credentials

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

Internal Server Error

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

Failure and Error Response Details

A failure or error response from the API 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
400	"transactionId" is required	The request does not contain the transaction identification number.
400	No Records Found	No records were found for the provided request.
401	Missing/Invalid credentials	The request either does not contain the mandatory credentials or contains invalid credentials.
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.

API Limitations

1. The EPFO Employee Verification API may fail for users who have worked at less than two companies. This is because successful verification requires employees to be registered on the Umang portal with their phone number. First-time employees often do not complete this registration until they leave their first job and realize they need to retain their UAN and log in with their phone.

2. According to a restriction from the Umang portal, once an OTP is sent, another cannot be sent within 60 minutes. However, after the OTP is sent, the Employment Details API can be called multiple times to retrieve the result.