Taxpayer Information

ClearTax provides APIs to verify if a GSTIN number is valid as per the Government.

• Never have a wrong GSTIN for your Vendor/Customer in your ERP.

• System/Product On-boarding Avoid GST Compliance errors.

• Improve overall efficiency by reducing back and forth due to mistakes in GSTINs.

• Get additional details related to the GSTIN you already have.

Get Taxpayer Profile

You can verify the GSTIN number and avoid any mistakes in invoice preparation, tax payments.

You can get the taxpayer profile of a GSTIN by submitting a GET request to the GST API with the following request headers.

URL query String:

GET: {{host}}/gst/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/gstin_verification?gstin={{GSTIN_NUMBER_HERE}}

Request parameters:

Parameters	Parameter Type	Type	Description
X-Cleartax-Auth-Token	Header	String	Mandatory. The auth token generated from ClearTax user id and password.
taxable_entity_id	Path	String	Required. This is the unique ID associated with the GSTIN in your account.
gstin	query	String	Required. GSTIN number you wanted to validate

Sample Request:

https://api.clear.in/gst/api/v0.2/taxable_entities/249ba4-7392-4fa2-b3a0-685c6c7ad87e/gstin_verification?gstin=29AAFCD5862R1ZR

Sample Response:

200

{
    "gstin": "29AAFCD5862R1ZR",
    "lgnm": "DEFMACRO SOFTWARE PRIVATE LIMITED",
    "stj": "LVO 015 A - BENGALURU",
    "ctj": "RANGE-ASD7",
    "rgdt": "01/07/2017",
    "ctb": "Private Limited Company",
    "dty": "Regular",
    "nba": [
        "Leasing Business",
        "Supplier of Services",
        "Recipient of Goods or Services",
        "Import",
        "Office / Sale Office"
    ],
    "sts": "Active",
    "cxdt": "",
    "tradeNam": "DEFMACRO SOFTWARE PRIVATE LIMITED",
    "stjCd": "KA004",
    "ctjCd": "YV0701",
    "pradr": {
        "addr": {
            "bnm": "Block 1",
            "st": "HOSUR MAIN ROAD",
            "loc": "BANGALORE",
            "bno": "23, 24 AMR TECH PARK",
            "stcd": "Karnataka",
            "flno": "First Floor",
            "lt": "",
            "lg": "",
            "dst": "Bengaluru (Bangalore) Urban",
            "city": "",
            "pncd": "560068"
        },
        "ntr": "Leasing Business, Supplier of Services, Recipient of Goods or Services, Import"
    },
    "adadr": [
        {
            "addr": {
                "bnm": "DSI Innovation Campus, AWFIS",
                "st": "Gharebhavipalya",
                "loc": "Bangalore",
                "bno": "Block A",
                "stcd": "Karnataka",
                "flno": "2nd Floor",
                "lt": "",
                "lg": "",
                "dst": "Bengaluru (Bangalore) Urban",
                "city": "",
                "pncd": "560068"
            },
            "ntr": "Office / Sale Office"
        },
        {
            "addr": {
                "bnm": "AMR Tech Park, Treebo",
                "st": "Hosur Main Road , Bommanahalli",
                "loc": "Bangalore",
                "bno": "Block 1, 23 and 24",
                "stcd": "Karnataka",
                "flno": "First Floor",
                "lt": "",
                "lg": "",
                "dst": "Bengaluru (Bangalore) Urban",
                "city": "",
                "pncd": "560068"
            },
            "ntr": "Office / Sale Office"
        }
    ],
    "filingFreq": "MONTHLY",
    "lastUpdated": "21/Sep/2020"
}

400

{
    "success": false,
    "message": "Invalid GSTIN format. Please enter a valid Format"
}

Taxpayer API Objects

Key	Type	Description
stjCd	String	State Jurisdiction Code
lgnm	String	Legal Name of Business
stj	String	State Jurisdiction
dty	String	Taxpayer type
adadr	Array	Additional Place of Business Fields
cxdt	Date [DD/MM/YYYY]	Date Of Cancellation
gstin	String	GSTIN of the Tax Payer
nba	Array	Nature of Business Activity
lstupdt	Date [DD/MM/YYYY]	Last Updated Date
rgdt	Date [DD/MM/YYYY]	Date of Registration
ctb	String	Constitution of Business
pradr	Object	Principal Place of Business objects.
tradeNam	String	Trade Name
sts	String	GSTIN Status
ctjCd	String	Centre Jurisdiction Code
ctj	String	Centre Jurisdiction

Principal Place of Business object & fields

Key	Type	Description
bnm	String	Building Name
st	String	Street
loc	String	Location
bno	String	Door Number
stcd	String	State Name
dst	String	District
city	String	City
flno	String	Floor Number
lt	String	Latitude
pncd	Integer	Pin Code
lg	String	Longitude
ntr	String	Nature of principle place of business
filingFreq	String	Filing frequency
lastUpdated	String	Date in which the provided GSTIN was last updated.

Get Taxpayer Compliance

URL query String:

GET: {{host}}/gst/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/returns_filing_status?gstin={{GSTIN_NUMBER_HERE}}

Request parameters:

Parameters	Parameter Type	Type	Description
X-Cleartax-Auth-Token	Header	String	Mandatory. The auth token generated from ClearTax user id and password.
taxable_entity_id	Path	String	Required. This is the unique ID associated with the GSTIN in your account.
gstin	Query	String	Required. GSTIN number you wanted to validate

Sample Request:

https://api.clear.in/gst/api/v0.2/taxable_entities/249f74-7392-4fa2-b3a0-685c6c7ad87e/returns_filing_status?gstin=29AAFCD5862R1ZR

Sample Response:

200

[
  {
      "EFiledlist": [
          {
              "arn": "AA2702188342463",
              "ret_prd": "022018",
              "mof": "ONLINE",
              "dof": "20-03-2018",
              "rtntype": "GSTR3B",
              "status": "Filed",
              "valid": "Y",
              "is_filed_through_ct": false,
              "filedThroughCT": false
          }
      ]
  },
  {
      "EFiledlist": [
          {
              "arn": "AB270219056196Y",
              "ret_prd": "022019",
              "mof": "ONLINE",
              "dof": "20-03-2019",
              "rtntype": "GSTR3B",
              "status": "Filed",
              "valid": "Y",
              "is_filed_through_ct": false,
              "filedThroughCT": false
          }
      ]
  },
  {
      "EFiledlist": [
          {
              "arn": "AB270220282959T",
              "ret_prd": "022020",
              "mof": "ONLINE",
              "dof": "20-03-2020",
              "rtntype": "GSTR3B",
              "status": "Filed",
              "valid": "Y",
              "is_filed_through_ct": false,
              "filedThroughCT": false
          }
      ]
  }
]

400

{
    "success": false,
    "message": "Invalid GSTIN format. Please enter a valid Format"
}

Filed list object & fields

Key	Type	Description
arn	String	GSTIN number
ret_prd	String	Return period
mof	String	Mode of filing
dof	String	Date of filing
rtntype	String	Return type
status	String	Filing status
valid	Boolean	Validity
is_filed_through_ct	String	If it's filed through ClearTax