GST Authentication API - v1

This document outlines the details of the 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.

Input	Output
The unique 15-digit GSTIN value	The business details associated with the GSTIN. The complete list of output fields is available in the Success Response Details section.

API URL

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

API Endpoint

searchGSTIN

Overview

The GST Authentication API - v1 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 GST Authentication API - v1.

API Request Details

Method - POST

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.	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	Not Applicable - this is a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	Not Applicable - any defined unique value mapped to a transaction in your business ecosystem

Input

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

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
gstin	Mandatory	string	The unique 15-digit GSTIN value	Not Applicable	Not Applicable

Request

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

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>"
}'

Success Response

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

{
  "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 from the GST Authentication API - v1:

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 GST Authentication API - v1:

Missing GSTIN

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

Missing/Invalid Credentials

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

Invalid GSTIN

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

Service Error

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

Error Response Details

A failure or error response from the GST Authentication API - v1 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	Error Resolution
400	gstin is required	The request did not include the gstin input	Include a valid gstin value in the request body
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey in the request headers. Check the dashboard's credentials tab
422	Invalid GSTIN pattern	The request has an incorrect GSTIN input that does not match the required 15-digit alphanumeric format	Provide a valid 15-digit alphanumeric GSTIN value in the request
504	Issue with external service	There is an issue with the service. Kindly contact the HyperVerge Team for support.	Retry the request after some time. If the issue persists, contact the HyperVerge team