GST Authentication API - v2

API Description

Objective

The GST Authentication API - v2 authenticates a GSTIN issued by the Goods and Services Tax Network (GSTN) in India, and retrieves the verified business details linked to the provided GSTIN.

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.

Input	Output
The 15-digit GSTIN number	The complete business profile including legal name, address details, jurisdiction information, business constitution, registration details, and additional business locations. The complete list of output fields is available in the Success Response Details section

API URL

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

API Endpoint

searchGSTINV2

Overview

The GST Authentication API - v2 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	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)

Input

The following table provides the details of the parameters required for the GST Authentication API - v2's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`gstin`	Mandatory	The unique 15-digit alphanumeric GSTIN value	Not Applicable	Not Applicable
`formatDate`	Optional	This parameter controls the date format in the response. When true, dates are returned as DD-MM-YYYY; when false, as DD/MM/YYYY	Boolean values	Not Applicable
`sendAddressList`	Optional	When enabled, this parameter returns the address list in the success response, i.e., the list of all corresponding addresses of the business	yes or no	no

Request

The following code snippet demonstrates a standard curl request for the GST Authentication API - v2:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/searchGSTINV2' \
--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_the_GSTIN_Number>",
    "formatDate": "<Enter_the_Format_Date>",
    "sendAddressList": "<Enter_yes_or_no>"
}'

Success Response

The following code snippet demonstrates a success response from the GST Authentication API - v2:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "code": 200,
    "data": {
      "gstin": "<GSTIN_Number>",
      "pradr": {
        "addr": {
          "blockName": "<Block_Name>",
          "street": "<Street>",
          "location": "<Location>",
          "doorNumber": "<Door_Number>",
          "state": "<State>",
          "flatNumber": "<Flat_Number>",
          "latitude": "<Latitude>",
          "longitude": "<Longitude>",
          "district": "<District>",
          "pincode": "<Pincode>"
        },
        "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>",
            "state": "<State>",
            "flatNumber": "<Flat_Number>",
            "latitude": "<Latitude>",
            "longitude": "<Longitude>",
            "district": "<District>",
            "pincode": "<Pincode>"
          },
          "natureOfBusiness": "<Nature_Of_Business>",
          "fullAddress": "<Full_Address>"
        },
        {
          "addr": {
            "blockName": "<Block_Name>",
            "street": "<Street>",
            "location": "<Location>",
            "doorNumber": "<Door_Number>",
            "state": "<State>",
            "flatNumber": "<Flat_Number>",
            "latitude": "<Latitude>",
            "longitude": "<Longitude>",
            "district": "<District>",
            "pincode": "<Pincode>"
          },
          "natureOfBusiness": "<Nature_Of_Business>",
          "fullAddress": "<Full_Address>"
        }
      ],
      "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>",
      "addressList": [ // returned when sendAddressList is enabled in the request body
        "<Address_1>",
        "<Address_2>",
        "<Address_3>",
        "<Address_4>",
        "<Address_5>",
        "<Address_6>",
        "<Address_7>",
        "<Address_8>",
        "<Address_9>",
        "<Address_10>",
        "<Address_11>",
        "<Address_12>",
        "<Address_13>",
        "<Address_14>",
        "<Address_15>"
      ]
    },
    "timestamp": <Timestamp>
  },
  "metadata": {
    "requestId": "<Request_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the GST Authentication API - v2:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The status code of the response
code	integer	The numeric status code of API response
gstin	string	The GST Identification Number
pradr	object	The principal address and business details
addr	object	The address details of the business
blockName	string	The block name of the business location
street	string	The street address of the business location
location	string	The location of the business
doorNumber	string	The door number of the business location
district	string	The district of the business location
latitude	string	The latitude coordinate of the business location
locality	string	The locality of the business location
pincode	string	The postal code of the business location
landMark	string	The landmark near the business location
state	string	The state of the business location
geocodelvl	string	The geocode level of the address
flatNumber	string	The flat number of the business location
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 enabled status
stateJurisdictionCode	string	The code for state tax jurisdiction
taxpayerType	string	The type of taxpayer
stateJurisdiction	string	The name of state tax jurisdiction
legalName	string	The registered legal name of the business
additionalPlaceOfBusiness	array	The list of other business locations
dateOfCancellation	string	The GST cancellation date
natureOfBusinessAtAddress	array	The list of business activities at addresses
lastUpdated	string	The last update date of the information
constitutionOfBusiness	string	The legal constitution of the business
registeredDate	string	The date of GST registration
centralJurisdictionCode	string	The central tax jurisdiction code
status	string	The current status of the GST registration
tradeName	string	The trade or brand name
centralJurisdiction	string	The name of central tax jurisdiction
addressList	array	The list of multiple addresses related to business
timestamp	integer	The timestamp of the response
requestId	string	The unique identifier for the request

Error Responses

The following are some error responses from the API:

Missing GSTIN
Missing/Invalid Credentials
Invalid GSTIN
Internal Server Error
Service Error

{
  "status": "failure",
  "statusCode": "400",
  "error": "gstin is required",
  "metadata": {
    "requestId": "<Request_ID>"
  }
}

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

{
  "status": "failure",
  "statusCode": "422",
  "error": {
    "code": 422,
    "message": "Invalid GSTIN pattern",
    "timestamp": <Timestamp>
  },
  "metadata": {
    "requestId": "<Request_ID>"
  }
}

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

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

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	gstin is required	The request is missing the `gstin` input or has invalid parameters in the request body
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 that is empty, invalid, or does not exist
500	Internal Server Error	The request has an internal server error. Please check the request headers or contact the HyperVerge team for investigation
504	Issue with external service	There is an issue with the external service. Please check the request headers or contact the HyperVerge team for investigation

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details​

Method - POST​

Headers​

Input​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​