GST Authentication API - v1

API Description

Objective

The GST Authentication API - v1 authenticates a 15 digit alphanumeric GSTIN input issued by the Goods and Service Tax Network in India and returns the details of the business associated with this GSTIN number.

info

The Goods and Services Tax Identification Number (GSTIN) is a 15-digit alphanumeric identifier for registered taxpayers in India. Refer to this page for a detailed explanation of how a GSTIN is constructed.

API URL

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

API Endpoint

searchGSTIN

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 ﬁles 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	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.
transactionId	Mandatory	Unique ID for the customer journey.	N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Request Body

The following table provides information on the parameters used in the request body of the API:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`gstin`	Mandatory	The unique 15-digit GSTIN value	Not Applicable	Not Applicable

Request

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

curl --location --request POST 'https://ind-engine.lookup.hyperverge.co/v1/searchGSTIN' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "gstin": "<Enter_GST_number>"
}'

Success Response

You will receive a success response in a format similar to the following code if the GSTIN input is correct:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "code": 200,
    "data": {
      "gstin": "<GSTIN_Number>",
      "pradr": {
        "addr": {
          "blockName": "<Block_Name>",
          "street": "<Street>",
          "location": "<Location>",
          "doorNumber": "<Door_Number>",
          "district": "<District>",
          "latitude": "<Latitude>",
          "locality": "<Locality>",
          "pincode": "<Pincode>",
          "landMark": "<Landmark>",
          "state": "<State>",
          "geocodelvl": "<Geocode_Level>",
          "flatNumber": "<Flat_Number>",
          "longitude": "<Longitude>"
        },
        "natureOfBusiness": "<Nature_Of_Business>",
        "fullAddress": "<Full_Address>"
      },
      "einvoiceStatus": "<E_Invoice_Status>",
      "stateJurisdictionCode": "<State_Jurisdiction_Code>",
      "taxpayerType": "<Taxpayer_Type>",
      "stateJurisdiction": "<State_Jurisdiction>",
      "legalName": "<Legal_Name>",
      "additionalPlaceOfBusiness": [
        {
          "addr": {
            "blockName": "<Block_Name>",
            "street": "<Street>",
            "location": "<Location>",
            "doorNumber": "<Door_Number>",
            "district": "<District>",
            "latitude": "<Latitude>",
            "locality": "<Locality>",
            "pincode": "<Pincode>",
            "landMark": "<Landmark>",
            "state": "<State>",
            "geocodelvl": "<Geocode_Level>",
            "flatNumber": "<Flat_Number>",
            "longitude": "<Longitude>"
          },
          "fullAddress": "<Full_Address>",
          "natureOfBusiness": "<Nature_Of_Business>"
        }
      ],
      "dateOfCancellation": "<Date_Of_Cancellation>",
      "natureOfBusinessAtAddress": [
        "<Nature_Of_Business>",
        "<Nature_Of_Business>",
        "<Nature_Of_Business>",
        "<Nature_Of_Business>"
      ],
      "lastUpdated": "<Last_Updated_Date>",
      "constitutionOfBusiness": "<Constitution_Of_Business>",
      "registeredDate": "<Registered_Date>",
      "centralJurisdictionCode": "<Central_Jurisdiction_Code>",
      "status": "<Status>",
      "tradeName": "<Trade_Name>",
      "centralJurisdiction": "<Central_Jurisdiction>"
    },
    "timestamp": <Timestamp>
  }
}

{ "status": "success", "statusCode": "200", "result": { "code": 200, "data": { "gstin": "<GSTIN_Number>", "pradr": { "addr": { "blockName": "<Block_Name>", "street": "<Street>", "location": "<Location>", "doorNumber": "<Door_Number>", "district": "<District>", "latitude": "<Latitude>", "locality": "<Locality>", "pincode": "<Pincode>", "landMark": "<Landmark>", "state": "<State>", "geocodelvl": "<Geocode_Level>", "flatNumber": "<Flat_Number>", "longitude": "<Longitude>" }, "natureOfBusiness": "<Nature_Of_Business>", "fullAddress": "<Full_Address>" }, "einvoiceStatus": "<E_Invoice_Status>", "stateJurisdictionCode": "<State_Jurisdiction_Code>", "taxpayerType": "<Taxpayer_Type>", "stateJurisdiction": "<State_Jurisdiction>", "legalName": "<Legal_Name>", "additionalPlaceOfBusiness": [ { "addr": { "blockName": "<Block_Name>", "street": "<Street>", "location": "<Location>", "doorNumber": "<Door_Number>", "district": "<District>", "latitude": "<Latitude>", "locality": "<Locality>", "pincode": "<Pincode>", "landMark": "<Landmark>", "state": "<State>", "geocodelvl": "<Geocode_Level>", "flatNumber": "<Flat_Number>", "longitude": "<Longitude>" }, "fullAddress": "<Full_Address>", "natureOfBusiness": "<Nature_Of_Business>" } ], "dateOfCancellation": "<Date_Of_Cancellation>", "natureOfBusinessAtAddress": [ "<Nature_Of_Business>", "<Nature_Of_Business>", "<Nature_Of_Business>", "<Nature_Of_Business>" ], "lastUpdated": "<Last_Updated_Date>", "constitutionOfBusiness": "<Constitution_Of_Business>", "registeredDate": "<Registered_Date>", "centralJurisdictionCode": "<Central_Jurisdiction_Code>", "status": "<Status>", "tradeName": "<Trade_Name>", "centralJurisdiction": "<Central_Jurisdiction>" }, "timestamp": <Timestamp> } }

Success Response Details

The following table provides the details of the fields in a success response:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The status code of the response
code	integer	The response code for the request
gstin	string	The GST identification number
pradr	object	The principal address details
addr	object	The address details of the principal place of business
street	string	The street address of the business
location	string	The location of the business
doorNumber	string	The door number of the business address
district	string	The district of the business location
latitude	string	The latitude coordinate of the business location
pincode	string	The postal code of the business location
state	string	The state of the business location
geocodelvl	string	The geocode level of the address
longitude	string	The longitude coordinate of the business location
natureOfBusiness	string	The nature of business activities at the principal address
fullAddress	string	The complete address of the principal place of business
einvoiceStatus	string	The e-invoice registration status
stateJurisdictionCode	string	The jurisdiction code of the state
taxpayerType	string	The type of taxpayer
stateJurisdiction	string	The state jurisdiction of the business
legalName	string	The legal name of the business
additionalPlaceOfBusiness	array	The list of additional places of business
dateOfCancellation	string	The date of cancellation of GST registration, if any
natureOfBusinessAtAddress	array	The types of business activities conducted at the address
lastUpdated	string	The last updated date of the business details
constitutionOfBusiness	string	The legal constitution of the business
registeredDate	string	The registration date of the business
centralJurisdictionCode	string	The central jurisdiction code
status	string	The current status of the GST registration
tradeName	string	The trade name of the business
centralJurisdiction	string	The central jurisdiction of the business
timestamp	integer	The timestamp of the response

Error Responses

The following code snippets show the sample error responses from the API:

Missing GSTIN
Missing/Invalid Credentials
Invalid GSTIN
Service Error

{
 "status":"failure",
 "statusCode":"400",
 "error":"gstin is required"
}

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

{
   "status":"failure",
   "statusCode":"422",
   "error":{
      "code":422,
      "message":"Invalid GSTIN pattern",
      "timestamp":1629118399096
   }
}

{
   "status":"failure",
   "statusCode":"504",
   "error":"Issue with external service"
}

Error Response Details

Status Code	Error	Error Description
400	gstin is required	The request did not have the `gstin` input
401	Missing/Invalid credentials	The request is either missing the mandatory credentials or has invalid credentials
422	Invalid GSTIN pattern	The request has an incorrect GSTIN input
504	Issue with external service	There is an issue with the service. Kindly contact the HyperVerge Team for support

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Request Body​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​