GST Authentication API

API Description

Objective

This GST Authentication API authenticates a 15 digit alphanumeric Goods and Services Tax Identification Number(GSTIN) issued by the Goods and Service Tax Network in India and returns the details of the business associated with this GSTIN.

Input	Output
The 15 digit GSTIN.	The details of the business asssociated with the GSTIN input.

API URL

https://ind-engine.thomas.hyperverge.co/v1/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 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.

Overview

This API authenticates a 15 digit alphanumeric Goods and Services Tax Identification Number(GSTIN) input issued by the Goods and Service Tax Network in India and returns the details of the business associated with this GSTIN number.

Document Type	API Name	Description
GSTIN - 15 Digits Input	searchGSTIN	Authenticates GSTIN.

Protocol

We recommend using HTTPS for all API calls. For HTTPS, only TLS v1.2 is supported to ensure better security. All data is received as JSON.

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 searchGSTIN API .

Parameter	Mandatory or Optional	Description
gstin	Mandatory	The unique 15-digit GSTIN value.

Sample Requests

Sample Request

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

curl --location --request POST 'https://ind-engine.thomas.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>"
}'

API Responses

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":"18AIBCB5518L1ZR",
      "stateJurisdictionCode":"AS035",
      "taxpayerType":"Regular",
      "stateJurisdiction":"GUWAHATI - A - 2",
      "legalName":"BKKAJ FINANCE LIMITED",
      "additionalPlaceOfBusiness":[
        {
          "addr":{
            "blockName":"",
            "street":"Moran Hut, Sd Complex, Nh 37 Moran, Moran Hat",
            "location":"Ps Khowang, Dist , Moran Assam, Dibrugarh",
            "doorNumber":"1st floor",
            "state":"Assam",
            "district":"Dibrugarh",
            "flatNumber":"",
            "latitude":"",
            "pincode":"786613",
            "longitude":""
          },
          "natureOfBusiness":"Supplier of Services"
        },
        {
          "addr":{
            "blockName":"",
            "street":"On Way Dhekilajuli, Tezpur Main Road",
            "location":"Opp. Indian Bank, Dhekiajuli",
            "doorNumber":"1st Floor, Ward No.6",
            "state":"Assam",
            "district":"Sonitpur",
            "flatNumber":"",
            "latitude":"",
            "pincode":"784110",
            "longitude":""
          },
          "natureOfBusiness":"Supplier of Services"
        }
      ],
      "dateOfCancellation":"",
      "natureOfBusinessAtAddress":[
        "Supplier of Services"
      ],
      "lastUpdated":"30/09/2021",
      "constitutionOfBusiness":"Public Limited Company",
      "registeredDate":"13/09/2017",
      "centralJurisdictionCode":"UQ0205",
      "status":"Active",
      "tradeName":"BKKAJ FINANCE LIMITED",
      "centralJurisdiction":"II-E RANGE"
    },
    "timestamp":1629119825803
  }
}

Success Response Details

A success response from the API reflects the success status with a status code of 200 and a result object containing the response data with the following attributes-value pair.

Attributes	Description	Values Returned
data	It returns the details of the business associated with the GSTIN number.	This is an object with values.

Failure Response Sample - Invalid GSTIN

You will receive an error response in a format similar to the following code sample if the request is correct but the module fails to find a match against the input.

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

Failure Response Details

A failure response from the module contains a failure status with a relavant status code and error object. The following table lists the failure response values.

Status Code	message	Error Description
422	Invalid GSTIN pattern	The request has an incorrect GSTIN input.