Establishment Advanced API

The following document highlights the details of the Establishment Advanced API.

API Description

Objective

The Establishment Advanced API retrieves registration details, compliance status, and historical filing information for a given organization (establishment).

Input	Output
Establishment name and establishment details count	Registration details (name, code, address, contact), compliance and exemption status, and historical ECR filing records. The complete list of output fields is available in the Success Response Details section

API URL

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

API Endpoint

establishmentAdvanced

Overview

The Establishment Advanced API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should send all inputs as a JSON body 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 Establishment Advanced 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 Establishment Advanced API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
establishmentName	Mandatory	string	The registered name of the establishment	Not Applicable	Not Applicable
establishmentDetailsCount	Mandatory	string	The maximum number of matching establishment records to include in the response	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Establishment Advanced API:

curl --location 'https://ind-engine.thomas.hyperverge.co/v1/establishmentAdvanced' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--data '{
  "establishmentName": "<Enter_the_Establishment_Name>",
  "establishmentDetailsCount": "<Enter_the_Establishment_Details_Count>"
}'

Success Response

The following code snippet demonstrates a success response from the Establishment Advanced API:

{
    "status": "success",
    "statusCode": 200,
    "result": [
        {
            "establishmentDetails": {
                "confidenceScore": "<Confidence_Score>",
                "establishmentName": "<Establishment_Name>",
                "establishmentCode": "<Establishment_Code>",
                "cinCode": "<CIN_Code>",
                "panStatus": "<PAN_Status>",
                "sectionApplicable": "<Section_Applicable>",
                "esicCode": "<ESIC_Code>",
                "ownershipType": "<Ownership_Type>",
                "address": "<Address>",
                "district": "<District>",
                "city": "<City>",
                "state": "<State>",
                "country": "<Country>",
                "pinCode": "<Pin_Code>",
                "epfoOfficeName": "<EPFO_Office_Name>",
                "epfoOfficeAddress": "<EPFO_Office_Address>",
                "zone": "<Zone>",
                "region": "<Region>",
                "primaryBusinessActivity": "<Primary_Business_Activity>",
                "dateOfSetup": "<Date_Of_Setup>",
                "estContact": "<Establishment_Contact>",
                "estEmail": "<Establishment_Email>"
            },
            "establishmentStatus": {
                "exemptionStatus": "<Exemption_Status>",
                "workingStatus": "<Working_Status>",
                "coverageSection": "<Coverage_Section>",
                "actionableStatus": "<Actionable_Status>",
                "dateOfCoverage": "<Date_Of_Coverage>"
            },
            "validityStatus": {
                "establishmentCode": "<Establishment_Code>",
                "establishmentName": "<Establishment_Name>",
                "establishmentStatus": "<Establishment_Status>",
                "registrationStatusOnEcrPortal": "<Registration_Status_On_ECR_Portal>",
                "postCoverageStatus": "<Post_Coverage_Status>"
            },
            "estHistoryDetails": [
                {
                    "totalAmount": "<Total_Amount>",
                    "employeesCount": "<Employees_Count>",
                    "wageMonth": "<Wage_Month>",
                    "filingDates": "<Filing_Dates>"
                }
            ]
        }
    ],
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the Establishment Advanced API:

Parameter	Type	Description
status	string	The status of the request
statusCode	number	The HTTP status code for the response
result	array	Array of matching establishment records
result[].establishmentDetails	object	Core registration and contact details of the establishment
result[].establishmentDetails.confidenceScore	number	Matching confidence score indicating how closely the input matched the establishment
result[].establishmentDetails.establishmentName	string	Official name of the establishment registered with EPFO
result[].establishmentDetails.establishmentCode	string	Unique EPFO code assigned to the establishment
result[].establishmentDetails.cinCode	string	Corporate Identification Number (CIN) of the establishment, if available
result[].establishmentDetails.panStatus	string	Status of the PAN associated with the establishment
result[].establishmentDetails.sectionApplicable	string	EPFO section under which the establishment is covered
result[].establishmentDetails.esicCode	string	ESIC code assigned to the establishment, if available
result[].establishmentDetails.ownershipType	string	Type of ownership of the establishment
result[].establishmentDetails.address	string	Registered address of the establishment
result[].establishmentDetails.district	string	District where the establishment is located
result[].establishmentDetails.city	string	City where the establishment operates
result[].establishmentDetails.state	string	State where the establishment is registered
result[].establishmentDetails.country	string	Country where the establishment operates
result[].establishmentDetails.pinCode	string	Postal PIN code of the establishment
result[].establishmentDetails.epfoOfficeName	string	Name of the EPFO office responsible for the establishment
result[].establishmentDetails.epfoOfficeAddress	string	Address of the EPFO office managing the establishment
result[].establishmentDetails.zone	string	EPFO administrative zone covering the establishment
result[].establishmentDetails.region	string	EPFO regional office jurisdiction
result[].establishmentDetails.primaryBusinessActivity	string	Primary business activity of the establishment
result[].establishmentDetails.dateOfSetup	string	Date when the establishment was set up
result[].establishmentDetails.estContact	string	Contact number associated with the establishment
result[].establishmentDetails.estEmail	string	Email address associated with the establishment
result[].establishmentStatus	object	Current operational and compliance status of the establishment
result[].establishmentStatus.exemptionStatus	string	EPFO exemption status for PF, Pension, and EDLI schemes
result[].establishmentStatus.workingStatus	string	Current operational status of the establishment
result[].establishmentStatus.coverageSection	string	EPFO coverage section applicable to the establishment
result[].establishmentStatus.actionableStatus	string	Actionable compliance status for the establishment
result[].establishmentStatus.dateOfCoverage	string	Date on which the establishment was brought under EPFO coverage
result[].validityStatus	object	Validity and registration status of the establishment on EPFO portals
result[].validityStatus.establishmentCode	string	EPFO code used for validity verification
result[].validityStatus.establishmentName	string	Establishment name used for validity verification
result[].validityStatus.establishmentStatus	string	Validity status of the establishment
result[].validityStatus.registrationStatusOnEcrPortal	string	Status of registration on the EPFO ECR portal
result[].validityStatus.postCoverageStatus	string	Post-coverage compliance status of the establishment
result[].estHistoryDetails	array	Historical EPFO filing records for the establishment
result[].estHistoryDetails[].totalAmount	string	Total PF contribution amount filed for the wage month
result[].estHistoryDetails[].employeesCount	string	Number of employees reported for the wage month
result[].estHistoryDetails[].wageMonth	string	Wage month for which the EPFO filing was submitted
result[].estHistoryDetails[].filingDates	string	Dates on which EPFO filings were submitted for the wage month
metaData	object	Metadata associated with the API transaction
metaData.requestId	string	Unique identifier for the API request
metaData.transactionId	string	Transaction identifier associated with the user journey

Error Responses

The following are some error responses from the Establishment Advanced API:

Missing establishmentName

{
    "message": "Input Validation Error: requires property \"establishmentName\"",
    "statusCode": 400,
    "status": "failure"
}

Missing establishmentDetailsCount

{
    "message": "Input Validation Error: requires property \"establishmentDetailsCount\"",
    "statusCode": 400,
    "status": "failure"
}

Invalid Input Parameter

{
    "status": "failure",
    "statusCode": 400,
    "error": "Invalid input parameter",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid Credentials

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

No Record Found

{
    "status": "failure",
    "statusCode": 404,
    "error": "No record found",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Too Many Requests

{
    "status": "failure",
    "statusCode": 429,
    "error": "Maximum retry limit exceeded",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Internal Server Error

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Source Down

{
    "status": "failure",
    "statusCode": 503,
    "message": "External source downtime",
    "error": "EXTERNAL_DOWNTIME",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message. The following table lists the error responses for the Establishment Advanced API:

Status Code	Error Message	Error Description	Error Resolution
400	Input Validation Error: requires property "establishmentName"	The establishmentName field is missing from the request payload	Include the establishmentName field in the request body
400	Input Validation Error: requires property "establishmentDetailsCount"	The establishmentDetailsCount field is missing from the request payload	Include the establishmentDetailsCount field in the request body
400	Invalid input parameter	The establishmentName or establishmentDetailsCount field is present but empty	Provide a non-empty value for the field
401	Missing/Invalid credentials	The request is missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid credentials
404	No record found	No establishment record matching the provided input exists in the source system	Verify the establishment name and retry with a valid input
429	Maximum retry limit exceeded	Too many requests were sent in a short period	Reduce the request frequency and retry after some time
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution	Check the request headers or contact the HyperVerge team for resolution
503	External source downtime	The upstream EPFO source is unavailable or experiencing downtime	Retry after some time or contact the HyperVerge team if the issue persists