Subscribe for Updates

GSTIN Advanced

GSTIN Verification, Details and E-Invoice Applicability

This API Documentation is now available in Clear Identity Demo hub here

GST Advanced API is used to get extensive details for a particular GSTIN.

When requesting data for a given GSTIN, basic data points are given always and some other data points are optional i.e., the user can choose to request the data points related to those fields by passing a "true" or "false" flag against these fields in the request.

Basic data points include legal name, trade name, constitution name, jurisdiction, aggregative turnover, ekyc status, einvoice mandatory status etc.

Optional Details include:

  • HSN details: All HSN codes associated with the GSTIN

  • Branch details: Address and other details of all branches

  • Filing details: All GST filing details - monthly for the current year and yearly for the previous years

  • Liability paid details: %liability paid by month in current year and yearly for the previous years.

If the users want any of the details of the above 4 options fields, they have to pass flag as "true" against needed fields and "false" against not needed fields. For more details, refer to sample request below.

Users should test this API with the auth token provided, however if running on a sandbox environment replace the api.clear.in in the URL with api-sandbox.clear.in

🚧 This API includes 5 flags, as per details in the documentation below. When running the API, Standard details flag is set to "true" by default and the other flags can be set to "true" or "false" as per need. One credit is deducted for every flag that is set to "true". E-Invoice applicability and Turnover Range is part of Standard Details flag (True by default).

🚧 Every flag set as true consumes one extra credit. So if you require fields from basic details section only, then rest of the flags need to be set to false. If you require Basic details and HSN details, the rest of the 3 flags need to be set to false.

Request Method

Post

Request URL

{baseUrl}/clearIdentity/v2/gstins/advanced-details

Sandbox: https://api-sandbox.clear.in/clearIdentity/v2/gstins/advanced-details

Production: https://api.clear.in/clearIdentity/v2/gstins/advanced-details

Request Headers

Parameter

Data Type

Field Validations

Description

x-cleartax-auth-token

String

NA

Mandatory. User auth token

Content-Type

String

Value should always be "application/json"

Mandatory. Content type of the request body.

x-clear-is-response-status-200

Boolean

true, false

Optional. Flag for legacy ERPs to receive response with HTTP Status as 200 always.

By default this will be set as false.

Request Path Params

There are no path parameters for this API.

Request Query Params

There are no query parameters for this API.

Request Body

ParameterData TypeField ValidationsDescription

gstin

String

MaxLength: 15

Regex: Valid GSTIN as per government.

Mandatory. The GSTIN for which details are requested.

hsnDetails

boolean

true or false

Optional. To be passed as “true” if the details of all hsn codes linked to the GSTIN are needed. Default value is false.

branchDetails

boolean

true or false

Optional. To be passed as “true” if the details of all branches linked to the GSTIN are needed. Default value is false.

filingDetails

boolean

true or false

Optional. To be passed as “true” if the filing details if the GSTIN are needed. Default value is false.

liabilityPaidDetails

boolean

true or false

Optional. To be passed as “true” if the details of all hsn codes linked to the GSTIN are needed.Default value is false.

Sample Request

curl --location --request POST 'https://api-sandbox.clear.in/clearIdentity/gstins/advanced-details' \
--header 'x-cleartax-auth-token: ${auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "gstin": "29AAXXX3822X1XX",
   "hsnDetails": false,
   "branchDetails": false,
   "filingDetails": false,
   "liabilityPaidDetails": false
}'

Response Status Codes

HTTP Status CodeDescription

200

"OK"

Details for the requested GSTIN are found in the government records. Response data is passed for every field as available. Note: Some data points may not exist in the records, in which case, the field responses will be blank but the HTTP status code will still be 200.

400

"Bad Request"

Input data is incorrect. Example: Provided GSTIN is not a valid 15 character GSTIN.

401

Authorisation Failed

404

"Not Found"

GSTIN is not valid or not found in the government records.

402

Payment Required

429

Too many requests

500

"Internal Server Error"

There is a server error either from the government side or our side. Need to try it after some time.

Response Schema

ParameterData TypeField ValidationsDescription

requestId

String

Max Length: 32

Mandatory. Unique identifier generated by Clear to trace any request. Users can share this while raising support cases. If there is no value, this will be an empty string.

basicDetails

Object

<BasicDetails>

N/A

Mandatory. Basic details object.

hsnDetails

Object<HsnDetails>

N/A

Optional. HSN details object. If the hsnDetails flag was false in the request, this will be null.

branchDetails

Object<BranchDetails>

N/A

Optional. Branch details object. If the branchDetails flag was false in the request, this will be null.

filingDetails

Object<FilingDetails>

N/A

Optional. Filing details object. If the filingDetails flag was false in the request, this will be null.

liabilityPaidDetails

Object<LiabilityPaidDetails>

N/A

Optional. Liability paid details object. If the liabilityPaidDetails flag was false in the request, this will be null.

Basic Details Object

ParameterData TypeField ValidationsDescription

natureOfCoreBusinessActivity

String

N/A

Nature of core business activity. It can have values such as:

"SPO": Service provider and Others

"TRD:TRR": Trader-Retailer

"MFT": Manufacturer

"TRD:TWD": Trader-Wholesaler/Distributor

aadhaarVerified

String

Yes or No

Indicates if Aadhaar is verified: Yes if verified, No if not verified

legalBusinessName

String

MaxLength: 255

The legal name of the entity that is registered at the time of incorporation of the business

gstin

String

MaxLength: 255

The Goods and Services Tax Identification Number

ekycFlag

String

Yes/No/Not Applicable

This field for the applicability of ekyc. Its responses are in “No”,“Yes”, and “Not Applicable”.

- If the response is “No," then ekyc is applicable but not done.

- If the response is “Yes” then ekyc is applicable and done.

- If the response is “Not Applicable” then ekyc is not applicable for the provided GST

compositionRate

String

MaxLength: 255

composition rate is applicable to any taxpayer whose turnover is less than 1.5cr. And the rate is 1% to 6% depending on their type of business. (Turnover Can be Revised by GST Dept time to time)

When value is NA, it is not applicable

constitutionOfBusiness

String

MaxLength: 255

Types of company/business. Some possible values include:

Hindu Undivided Family

Any other body notified by committee

AOP

C and F

Artificial Juridical Person

CENTRAL AUTONOMOUS BODY

Foreign Company

Local Authority

Statutory Body

Co. U/Sec 25 of companies Act,1956 Limited by shares not for profit

Branch of Foreign Company

Branch Office of Foreign Company

ASSOCIATION OF PERSONS

Body of Individuals

Proprietorship

Limited Liability Partnership

Partnership

Private Limited Company

Public Limited Company

tradeName

String

MaxLength: 255

The trade name of the entity: A trade name is also called a fictitious or a business name and is different from the legal and registered name of the business.

centralJurisdiction

String

MaxLength: 255

Central Jurisdiction

percentTaxInCash

String

MaxLength: 255

Composition taxpayers pays the tax in cash: It’s the amount of tax paid in cash out of the total outward liability collected

aggreTurnOverFY

String

MaxLength: 255

Fiscal Year of Aggregate Turnover reported

stateJurisdiction

String

MaxLength: 255

State Jurisdiction

registrationType

String

MaxLength: 255

Types of Taxpayers. Possible values include Regular, Exempted, Composition

aggreTurnOver

String

MaxLength: 255

Aggregate Turnover Slab

cancellationDate

String

DD/MM/YYYY

The cancellation date (if applicable)

businessNature

Array

MaxLength: 255

The nature of the business (Office/Sale Office, Others, Warehouse/Depot, Supplier of Services etc)

registrationDate

String

DD/MM/YYYY

Registration date of business in GST

registrationStatus

String

Active, Inactive, Cancelled on application of Taxpayer

Status of Registration

percentTaxInCashFY

String

N/A

Fiscal Year in which the amount of tax paid was in cash out of the total outward liability collected.

isEInvoiceOpted

String

Yes, No

Whether the GSTIN has opted for einvoice.

Yes - GSTIN has opted for e-invoice

No- GSTIN has not opted for e-invoice

memberDetails

Array<String>

N/A

Names of the Directors/Proprietors/Promoters. If the value is null, then this will return an empty list.

isEInvoiceMandated

String

Yes, No

Is einvoice mandatory?

Yes for Taxpayers with annual turnover greater than the amount announced by government (>10Cr before August 1st 2023, > 5Cr from 1st August 2023)

No for Taxpayers with annual turnover less than the amount announced by government

HsnDetails Object

ParameterData TypeField ConstraintsDescription

goods

Array <HsnType>

NA

List of all the HSN codes of goods the company deals in.

services

Array <HsnType>

NA

List of all the HSN codes of services the company deals in.

HsnDescription Object

ParameterData TypeField ConstraintsDescription

hsnCode

String

MaxLength: 8

The HSN code for a service or product

hsnDescription

String

Max length: 255

The description of the corresponding HSN code

BranchDetails Object

ParameterData TypeField ConstraintsDescription

principalAddress

Object <Address>

N/A

The permanent address details

additionalAddresses

Array <Address>

N/A

Addresses of additional branches or locations

Address Object

ParameterData TypeField ConstraintsDescription

address

String

Max length: 255

The address of a branch or additional location

natureOfBusiness

String

Max length: 255

The type of business deals conducted at the address

FilingDetails Object

ParameterData TypeField ConstraintsDescription

filingStatus

List<List<FilingStatus>>

N/A

List of list of filing status details

FilingStatus Object

ParameterData TypeField ConstraintsDescription

finYear

String

YYYY-YYYY

Financial year

returnPeriod

String

“Month Name” in case of monthly filing,

“Annual” in case of annual filing,

-“Month Name - Month Name” in case of quarterly filing

The filing period .

Eg: January, Annual, Jan-Mar

modeOfFiling

String

Max length: 255

Mode of filing. Example: ONLINE,OFFLINE

dateOfFiling

String

DD/MM/YYYY

Date of filing

returnType

string

GSTR1, GSTR3B, GSTR9 etc.

The type of return (e.g., GSTR1, GSTR3B, GSTR9)

LiabilityPaidDetails Object

ParameterData TypeField ConstraintsDescription

currFinYear

String

YYYY

The current financial year. If the current financial year is April 2023 - March 2024, then the value passed here would be 2023.

prevFinYear

String

YYYY

The previous financial year. If the previous financial year was April 2022 - March 2023, then the value passed here would be 2022.

prevTotalPct

Integer

N/A

The total percentage for the previous financial year.

currDetails

Array<PeriodDetails>

N/A

An array of objects containing details for the current year in two fields: “period” and “liabPaidPct”

prevDetails

Array<PeriodDetails>

N/A

An array of objects containing details for the previous year in two fields: “period” and “liabPaidPct”

PeriodDetails Object

ParameterData TypeField ConstraintsDescription

period

String

Max Length: 255

The period associated with the liability payment percentage. Eg: Jun-22

liabPaidPct

Number

N/A

The liability payment percentage for the specified period.

Sample Responses (Success)

Valid GSTIN and all 4 flags passed as true

Request Body

{
    "gstin": "27AAHPS2653Q1ZY",
    "hsnDetails": true,
    "branchDetails": true,
    "filingDetails": true,
    "liabilityPaidDetails": true
}

Metered (Charged or Credits Consumed for the API call) : Yes.

HTTP Status Code: 200

Response Body:

{
    "requestId": "71fd1a39-c880-4214-baa6-768e427649c0",
    "basicDetails": {
        "gstin": "27AAHPS2653Q1ZY",
        "ekycFlag": "Not Applicable",
        "compositionRate": "NA",
        "percentTaxInCash": "NA",
        "aggreTurnOverFY": "2021-2022",
        "registrationType": "Regular",
        "aggreTurnOver": "Slab: Rs. 0 to 40 lakhs",
        "businessNature": [
            "Works Contract",
            "Wholesale Business",
            "Service Provision"
        ],
        "registrationDate": "01/07/2017",
        "registrationStatus": "Active",
        "percentTaxInCashFY": "",
        "memberDetails": [
            "RAVINDRA CHIMANLAL  SHAH "
        ],
        "natureOfCoreBusinessActivity": "TRD:TRR",
        "aadhaarVerified": "Yes",
        "legalBusinessName": "RAVINDRA CHIMANLAL SHAH",
        "constitutionOfBusiness": "Proprietorship",
        "tradeName": "HERITAGE ENGINEERING",
        "centralJurisdiction": "Commissionerate - THANE,Division - DIVISION II,Range - RANGE-III",
        "isEInvoiceMandated": "No",
        "stateJurisdiction": "State - Maharashtra,Zone - MUMBAI_SOUTH_WEST,Division - KANDIVALI,Charge - KANDIVALI-WEST_710 (Jurisdictional Office)",
        "cancellationDate": "",
        "isEInvoiceOpted": "No"
    },
    "hsnDetails": {
        "goods": [
            {
                "hsnCode": "84663020",
                "hsnDescription": "PARTS AND ACCESSORIES SUITABLE FOR USE SOLELY OR PRINCIPALLY WITH THE MACHINES OF HEADINGS 8456 TO 8465, INCLUDING WORK OR TOOL HOLDERS, SELF-OPENING DIEHEADS, DIVIDING HEADS AND OTHER SPECIAL ATTACHMENTS FOR MACHINE-TOOLS; TOOL HOLDERS FOR ANY TYPE OF TOOL, FOR WORKING IN THE HAND - DIVIDING HEADS AND OTHER SPECIAL ATTACHMENTS FOR MACHINE-TOOLS: JIGS AND FIXTURES"
            },
            {
                "hsnCode": "84131110",
                "hsnDescription": "PUMPS FOR LIQUIDS, WHETHER OR NOT FITTED WITH A MEASURING DEVICE; LIQUID ELEVATORS - PUMPS FITTED OR DESIGNED TO BE FITTED WITH A MEASURING DEVICE: 8413 11 - PUMPS FOR DISPENSING FUEL OR LUBRICANTS, OF THE TYPE USED IN FILLING STATIONS OR IN GARAGES: HAND PUMPS"
            },
            {
                "hsnCode": "84131990",
                "hsnDescription": "PUMPS FOR LIQUIDS, WHETHER OR NOT FITTED WITH A MEASURING DEVICE; LIQUID ELEVATORS - PUMPS FITTED OR DESIGNED TO BE FITTED WITH A MEASURING DEVICE: OTHER :- OTHER: OTHER"
            }
        ],
        "services": [
            {
                "hsnCode": "00440306",
                "hsnDescription": "SITE PREPARATION AND CLEARANCE"
            },
            {
                "hsnCode": "00440410",
                "hsnDescription": "WORKS CONTRACT SERVICES"
            }
        ]
    },
    "branchDetails": {
        "message": "",
        "principalAddress": {
            "address": "SECOUND, 203, SYMPHONYCO OP HSG SOCIETY, CHARCOP MAIN ROAD, GANESH NAGAR, KANDIVALI WEST, Mumbai Suburban, Maharashtra, 400067",
            "natureOfBusiness": "Works CodealsInact, Wholesale Business, Service Provision"
        },
        "additionalAddresses": []
    },
    "filingDetails": {
        "filingStatus": [
            [
                {
                    "finYear": "2023-2024",
                    "returnType": "GSTR1",
                    "returnPeriod": "June",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "11/07/2023"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR1",
                    "returnPeriod": "March",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "12/04/2023"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR1",
                    "returnPeriod": "February",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "22/02/2023"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR1",
                    "returnPeriod": "January",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "13/02/2023"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR1",
                    "returnPeriod": "December",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "09/01/2023"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR1",
                    "returnPeriod": "September",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "13/10/2022"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR1",
                    "returnPeriod": "August",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "13/09/2022"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR1",
                    "returnPeriod": "July",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "12/08/2022"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR1",
                    "returnPeriod": "June",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "12/07/2022"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR1",
                    "returnPeriod": "April",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "13/05/2022"
                },
                {
                    "finYear": "2023-2024",
                    "returnType": "GSTR3B",
                    "returnPeriod": "June",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "19/07/2023"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR3B",
                    "returnPeriod": "March",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "20/04/2023"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR3B",
                    "returnPeriod": "December",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "19/01/2023"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR3B",
                    "returnPeriod": "September",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "21/10/2022"
                },
                {
                    "finYear": "2022-2023",
                    "returnType": "GSTR3B",
                    "returnPeriod": "June",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "19/07/2022"
                },
                {
                    "finYear": "2021-2022",
                    "returnType": "GSTR3B",
                    "returnPeriod": "March",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "19/04/2022"
                },
                {
                    "finYear": "2021-2022",
                    "returnType": "GSTR3B",
                    "returnPeriod": "December",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "18/01/2022"
                },
                {
                    "finYear": "2021-2022",
                    "returnType": "GSTR3B",
                    "returnPeriod": "September",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "19/10/2021"
                },
                {
                    "finYear": "2021-2022",
                    "returnType": "GSTR3B",
                    "returnPeriod": "June",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "21/07/2021"
                },
                {
                    "finYear": "2020-2021",
                    "returnType": "GSTR3B",
                    "returnPeriod": "March",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "20/04/2021"
                },
                {
                    "finYear": "2017-2018",
                    "returnType": "GSTR9",
                    "returnPeriod": "Annual",
                    "modeOfFiling": "ONLINE",
                    "dateOfFiling": "10/12/2019"
                }
            ]
        ]
    },
    "liabilityPaidDetails": {
        "currFinYear": "2023",
        "prevFinYear": "2022",
        "prevTotalPct": 100,
        "currDetails": [
            {
                "period": "Jun-23",
                "liabPaidPct": 100
            }
        ],
        "prevDetails": [
            {
                "period": "Jun-22",
                "liabPaidPct": 100
            },
            {
                "period": "Sep-22",
                "liabPaidPct": 100
            },
            {
                "period": "Dec-22",
                "liabPaidPct": 100
            },
            {
                "period": "Mar-23",
                "liabPaidPct": 100
            }
        ]
    },
}

Valid GSTIN and all 4 flags passed as false

Request Body

{
    "gstin": "29AAECC3822D1ZY",
    "hsnDetails": false,
    "branchDetails": false,
    "filingDetails": false,
    "liabilityPaidDetails": false
}

Metered(Charged or Credits Consumed for the API call) : Yes.

HTTP Status Code: 200

Response Body:

{
   "requestId": "4a07b1db-8a7b-4ca2-8a34-bdf6325d759c",
   "basicDetails": {
       "gstin": "29AAECC3822D1ZY",
       "ekycFlag": "No",
       "compositionRate": "NA",
       "percentTaxInCash": "NA",
       "aggreTurnOverFY": "2021-2022",
       "registrationType": "Regular",
       "aggreTurnOver": "Slab: Rs. 5 Cr. to 25 Cr.",
       "businessNature": [
           "Recipient of Goods or Services",
           "Supplier of Services"
       ],
       "registrationDate": "30/06/2017",
       "registrationStatus": "Active",
       "percentTaxInCashFY": "",
       "memberDetails": [
           "Sanjay Gupta ",
           "Sandeep Gupta ",
           "ASHISH KUMAR JAISWAL "
       ],
       "natureOfCoreBusinessActivity": "SPO",
       "aadhaarVerified": "No",
       "legalBusinessName": "Clearsharp Technology Private Limited",
       "constitutionOfBusiness": "Private Limited Company",
       "tradeName": "NA",
       "centralJurisdiction": "Commissionerate - BENGALURU-SOUTH,Division - SOUTH DIVISION-7,Range - RANGE-ASD7 (Jurisdictional Office)",
       "isEInvoiceMandated": "No",
       "stateJurisdiction": "State - Karnataka,Division - DGSTO-4, Bengaluru, LOCAL GST Office - LGSTO 016- Bengaluru",
       "cancellationDate": "",
       "isEInvoiceOpted": "Yes"
   },
   "hsnDetails": null,
   "branchDetails": null,
   "filingDetails": null,
   "liabilityPaidDetails": null
}

Valid GSTIN and all 1 flag passed as true

Request Body:

{
    "gstin": "29AAECH3221K1ZL",
    "hsnDetails": true,
    "branchDetails": false,
    "filingDetails": false,
    "liabilityPaidDetails": false
}

Metered (Charged or Credits Consumed for the API call) : Yes.

HTTP Status Code: 200

Response Body:

{
  "requestId": "adafd3fe-a9ea-438d-b3cd-4ddb0684bb94",
  "basicDetails": {
    "natureOfCoreBusinessActivity": "SPO",
    "aadhaarVerified": "No",
    "legalBusinessName": "HIVELOOP LOGISTICS PRIVATE LIMITED",
    "gstin": "29AAECH3221K1ZL",
    "ekycFlag": "No",
    "compositionRate": "NA",
    "constitutionOfBusiness": "Private Limited Company",
    "tradeName": "HIVELOOP LOGISTICS PRIVATE LIMITED",
    "centralJurisdiction": "Commissionerate - BENGALURU EAST,Division - EAST DIVISION-8,Range - RANGE-BED8 (Jurisdictional Office)",
    "percentTaxInCash": "Slab: 10 to 20%",
    "aggreTurnOverFY": "2021-2022",
    "stateJurisdiction": "State - Karnataka,Division - DGSTO-4, Bengaluru, LOCAL GST Office - LGSTO 016- Bengaluru",
    "registrationType": "Regular",
    "aggreTurnOver": "Slab: Rs. 500 Cr. and above",
    "cancellationDate": "",
    "businessNature": [
      "Office / Sale Office",
      "Others",
      "Warehouse / Depot",
      "Supplier of Services"
    ],
    "registrationDate": "23/02/2018",
    "registrationStatus": "Active",
    "percentTaxInCashFY": "2022-2023",
    "isEInvoiceOpted": "Yes",
    "memberDetails": [
      "PRADEEP  YADAV ",
      "Erikaa Kathuria  "
    ],
    "isEInvoiceMandated": "Yes"
  },
  "hsnDetails": {
    "services": [
      {
        "hsnCode": "00440262",
        "hsnDescription": "TRANSPORT OF GOODS BY ROAD"
      },
      {
        "hsnCode": "00440266",
        "hsnDescription": "TRANSPORT OF GOODS BY AIR"
      },
      {
        "hsnCode": "00440193",
        "hsnDescription": "STORAGE AND WAREHOUSE SERVICE"
      },
      {
        "hsnCode": "00440366",
        "hsnDescription": "BUSINESS SUPPORT SERVICES"
      }
    ]
  }
}

Sample Response (Error)

Based on the value set for the request parameter x-clear-is-response-status-200 the HTTP Status Code and response schema will defer. For more information, refer to legacy support.

Invalid GSTIN - All flags false

Request Body:

{
    "gstin": "23AAFCD5862R1ZR",
    "hsnDetails": false,
    "branchDetails": false,
    "filingDetails": false,
    "liabilityPaidDetails": false
}

Metered(Charged or Credits Consumed for the API call) : Yes.

HTTP Status Code: 404

Response Body:

{
  "errors": [
    {
      "error_code": "IDEN-005",
      "error_message": "GSTIN - 23AAFCD5862R1ZR is not valid and not present in government records",
      "error_source": "TP",
      "error_resolution": "Please give a valid GSTIN that's existing"
    }
  ]
}

Invalid GSTIN - 1 flag true

Request Body:

{
    "gstin": "23AAFCD5862R1ZR",
    "hsnDetails": true,
    "branchDetails": false,
    "filingDetails": false,
    "liabilityPaidDetails": false
}

Metered: Yes.

HTTP Status Code: 404

Response Body:

{
  "errors": [
    {
      "error_code": "IDEN-005",
      "error_message": "GSTIN - 23AAFCD5862R1ZR is not valid and not present in government records",
      "error_source": "TP",
      "error_resolution": "Please give a valid GSTIN that's existing"
    }
  ]
}

Invalid GSTIN - 1 flag syntax incorrect

Request Body:

{
    "gstin": "23AAFCD5862R1ZR",
    "hsnDetails": tue,
    "branchDetails": false,
    "filingDetails": false,
    "liabilityPaidDetails": false
}

Metered(Charged or Credits Consumed for the API call) : No.

HTTP Status Code: 400

Response Body:

{
    "timestamp": 1683559270680,
    "status": 400,
    "error": "Bad Request",
    "path": "/clearIdentity/v1/gst-advanced"
}

Incorrect GSTIN format - All flags false

Request Body:

{
    "gstin": "37BXWPG3678L",
    "hsnDetails": true,
    "branchDetails": false,
    "filingDetails": false,
    "liabilityPaidDetails": false
}

Metered: No.

HTTP Status Code: 400

Response Body:

{
  "errors": [
    {
      "error_code": "IDEN-006",
      "error_message": "gstin -37BXWPG3678L is not a 15 char valid GSTIN",
      "error_source": "CT",
      "error_resolution": "Please give a valid 15 char GSTIN"
    }
  ]
}

Incorrect Authtoken

Request Body:

{
    "gstin": "23AAFCD5862R1ZR",
    "hsnDetails": tue,
    "branchDetails": false,
    "filingDetails": false,
    "liabilityPaidDetails": false
}

Metered: No

HTTP Status Code: 401

Response Body:

{
        "errors": [
             {
            "error_code": "IDEN-001",
            "error_message": "Authorisation failed for given authToken",
            "error_source": "CT",
            "error_resolution": “Please provide a valid authToken”
        }
    ]
}

Verification service is down

Metered: No

HTTP Status Code: 500

Response Body:

{
        "errors": [
             {
            "error_code": "IDEN-007",
            "error_message": "Unable to process Request at the moment. Please try again Later",
            "error_source": "CT",
            "error_resolution": “Contact cleartax support if issue persists.”
        }
    ]
}

Usage increased

Metered: No

HTTP Status Code: 402

Response Body:

{
      "errors": [
             {
            "error_code": "IDEN-002",
            "error_message": "API usage limit has reached threshold",
            "error_source": "CT",
            "error_resolution": “Get threshold limit increased for given API”
        }
    ]
}

Too many requests

Metered: No

HTTP Status Code: 429

Response Body:

{
      "errors": [
             {
            "error_code": "IDEN-003",
            "error_message": "Requests exceeded rate limit",
            "error_source": "CT",
            "error_resolution": “Ensure calls per minute are within the specified range”
        }
    ]
}

API Validations

If the syntax of any of the 4 input flags (HSN details, Branch details, filing details and liability details) is incorrect (different from "true" or "false") the api will not be called.

API Constraints

The constraints for this API are -

  1. Licensing and metering against resource : GSTIN_ADVANCED - If the licensed threshold is exceeded, then the API will return error 406.

  2. Authentication: The request needs to have a valid access token.

  3. Credit limit: As per the plan purchased

PreviousGSTIN Return Filing StatusNextInvoicing API Reference

Last updated