Shops and Establishment Verification API

This document highlights the Shops and Establishment Verification API details.

API Description

Objective

The Shops and Establishment Verification API, fetches the details of an establishment or shop from the registration number and state name.

API URL

https://ind-thomas.hyperverge.co/v1/verifyShopAndEstablishmentLicense

API Endpoint

verifyShopAndEstablishmentLicense

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.

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 complainant journey	This should be both unique and easily associated with the complainant's journey in your application(s)

Input

The following table outlines the parameters required in the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
registrationNumber	The unique identifier or number required for registration	Mandatory	Not Applicable	Not Applicable

Request

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

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

Success Response

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

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "establishmentName": "<Establishment_Name>",
        "establishmentCode": "<Establishment_Code>",
        "primaryBusinessActivity": "<Primary_Business_Activity>",
        "address": "<Establishment_Address>",
        "city": "<City_Name>",
        "state": "<State_Name>",
        "district": "<District_Name>",
        "pincode": "<Pincode>",
        "establishmentStatus": "<Establishment_Status>",
        "registrationStatus": "<Registration_Status>",
        "dateOfCoverage": "<Date_Of_Coverage>",
        "working_status": "<workingStatus>",
        "excemptionStatus": "<Exemption_Status>",
        "actionableStatus": "<Actionable_Status>"
    },
    "metaData": {
        "requestId": "<Unique_Request_Identifier>",
        "transactionId": "<Unique_Transaction_Identifier>"
    }
}

Success Response Details

Parameter	Type	Description
establishmentName	string	The name of the organization or business
establishmentCode	string	The unique code assigned to the establishment
primaryBusinessActivity	string	The main business or industry type of the establishment
address	string	The registered address of the establishment
city	string	The city where the establishment is located
state	string	The state where the establishment is located
district	string	The district of the establishment
pincode	string	The postal code of the establishment's address
establishmentStatus	string	The current EPFO-related status; may refer to legacy or outdated registration
registrationStatus	string	The status of EPFO login creation or registration
dateOfCoverage	string	The date when the establishment was covered under EPFO
workingStatus	string	Indicates whether the establishment is currently operational or closed
excemptionStatus	string	The status of PF, Pension, and EDLI exemption
actionableStatus	string	Indicates if any EPFO action is pending or required

Error Responses

The following are the error responses from the API:

Registration Number Empty

{
    "status": "failure",
    "statusCode": 400,
    "error": "Please provide valid registration number",
    "metaData": {
        "requestId": "",
        "transactionId": ""
    }
}

Registration Number Not Found

{
    "status": "failure",
    "statusCode": 404,
    "error": "Registration Number Not Found.",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Multiple Records Found

{
    "status": "failure",
    "statusCode": 404,
    "error": "Multiple record found.",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Input Validation Error

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

Missing/Invalid Credentials

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

Internal Server Error

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

External Downtime

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

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 Message	Error Description
400	Missing required request parameters	Some mandatory request parameters are missing in the API request made
400	Please provide valid registration number	The registration number should not be empty in request body
401	Missing/Invalid credentials	The appId / appKey is missing or incorrect in the request headers
403	Please reach out to HV support Team	Please reach out to HV support Team
404	Registration Number Not Found	When registration number not found
404	Multiple record found	When multiple record found with the provided registration number
500	Internal Server Error	Check API request headers and/or contact HV for investigation
503	External Downtime	External downtime