EPFO Employment History - Mobile

API Description

Objective

The EPFO Employment History - Mobile API retrieves the Universal Account Number (UAN) and the complete employment history details associated with a mobile number from the Employees' Provident Fund Organisation records.

Input	Output
Mobile number and consent	The UAN and complete employment history including name, guardian name, establishment name, member ID, and date of joining for all employment records. The complete list of output fields is available in the Success Response Details section

API URL

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

API Endpoint

fetchEpfoHistory

Overview

The EPFO Employment History - Mobile 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.

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	Valid 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.

Input

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

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
mobileNumber	Mandatory	The 10-digit mobile number associated with the EPFO account	10-digit mobile number	Not Applicable
consent	Mandatory	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 Employment History - Mobile API:

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

Success Response

The following code snippet demonstrates a success response from the EPFO Employment History - Mobile API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "message": "UAN fetched from mobile.",
    "uanList": [
      "<UAN_Number>"
    ],
    "employmentData": [
      {
        "name": "<Employee_Name>",
        "guardianName": "<Guardian_Name>",
        "establishmentName": "<Establishment_Name>",
        "memberId": "<Member_ID>",
        "dateOfJoining": "<Date_Of_Joining>"
      },
      {
        "name": "<Employee_Name>",
        "guardianName": "<Guardian_Name>",
        "establishmentName": "<Establishment_Name>",
        "memberId": "<Member_ID>",
        "dateOfJoining": "<Date_Of_Joining>"
      }
    ]
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the EPFO Employment History - Mobile 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 UAN and employment history data
message	string	The message indicating the status of the UAN fetch operation
uanList	array	The Universal Account Number (UAN) retrieved from the mobile number
employmentData	array	The array of employment history objects containing all employment records
name	string	The full name of the individual
guardianName	string	The name of the individual's guardian
establishmentName	string	The name of the company or organization where the individual was employed
memberId	string	The unique identification number assigned to the individual within the organization or employment system
dateOfJoining	string	The date when the individual started working at the establishment
metaData	object	The metadata object containing request tracking information
requestId	string	The unique identifier for the request
transactionId	string	The transaction identifier for tracking

Failure Response

The following code snippet demonstrates a response when no UANs are found for the provided mobile number:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "message": "Provided mobile number doesn't have any UAN."
  },
  "metaData": {
    "requestId": "<Request_ID>"
  }
}

Error Responses

The following are some error responses from the API:

Invalid Mobile Number

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

Input Validation Error

{
  "message": "Input Validation Error: does not meet minimum length of 10",
  "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"
}

Failure and Error Response Details

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

Status Code	Error	Error Description
400	Provide a valid mobile number	The request has an invalid mobile number that contains special characters or is not properly formatted
400	Input Validation Error: does not meet minimum length of 10	The request has a mobile number that is less than or greater than 10 digits
400	Please provide consent	The request is missing the consent parameter or has an invalid consent value
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
500	Internal Server Error	The request has an internal server error. Please check the request headers or contact the HyperVerge team for investigation
503	Service Unavailable	The EPFO service is currently unavailable. Please try again later or contact the HyperVerge team for investigation