EPFO Employment History - UAN

Objective

The EPFO Employment History - UAN API retrieves the employment history details associated with a Universal Account Number(UAN).

Input	Output
The UAN and consent from the user	The user's employment data including: Name Guardian's Name Establishment Name Member ID Date of Joining

API URL

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

API Endpoint

uanEpfoHistory

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	Allowed Values
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 fields required for the API's request body.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
uanNumber	The UAN associated with the user's EPFO account	Mandatory	A valid 12 digit UAN identifier	Not Applicable
consent	The user's consent	Mandatory	"Y" for yes or "N" for no	Not Applicable

Request

The following code shows a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/uanEpfoHistory' \
--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": "<UAN_Number>",
    "consent": "<Consent>"
}'

Success Response

The following is a sample of a success response from the API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "message": "Employment history fetched.",
        "employmentData": [
            {
                "name": "<Name_of_the_User>",
                "guardianName": "<Guardian_Name>",
                "establishmentName": "<Establishment_Name>",
                "memberId": "<Member_ID>",
                "dateOfJoining": "<Date_Of_Joining_in_YYYY-MM-DD_Format>"
            },
            {
                "name": "<Name_of_the_User>",
                "guardianName": "<Guardian_Name>",
                "establishmentName": "<Establishment_Name>",
                "memberId": "<Member_ID>",
                "dateOfJoining": "<Date_Of_Joining_in_YYYY-MM-DD_Format>"
            },
            {
                "name": "<Name_of_the_User>",
                "guardianName": "<Guardian_Name>",
                "establishmentName": "<Establishment_Name>",
                "memberId": "<Member_ID>",
                "dateOfJoining": "<Date_Of_Joining_in_YYYY-MM-DD_Format>"
            }
        ]
    },
    "metaData": {
        "requestId": "<Request_ID>"
    }
}

Success Response Details

Parameter	Type	Description
employmentData	string	The employment details such as the user's name, guardian name, establishment name, member ID and date of joining
name	string	The full name of the user
guardianName	string	The name of the user's guardian
memberId	string	The unique identification number assigned to the user within the organization or employment system
dateOfJoining	string	The date when the user started working at the establishment

Failure Response

The following is a sample response for valid mobile number with no employment records:

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

Error Responses

The following are some sample error responses from the API.

Invalid UAN Number

The following is a sample response for an invalid UAN Number.

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

Input Validation Error

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

Missing Consent

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

Invalid Credentials

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

Internal Server Error

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

Failure and Error Response Details

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

Status Code	Error Message	Error Description
400	Missing required request parameters	Some mandatory request parameters are missing in the API request made. Check if "mobileNumber" and "consent" are given in request body
400	Provide a valid UAN number	The entered UAN is invalid
400	Please provide consent	The value for consent parmater is missing or has the value "N" (no)
401	Missing/Invalid credentials	The appId/ appKey is missing or incorrect in the request headers
403	Access Denied	Please contact the HyperVerge team
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution