Links

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
400
{
"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"
}
{
"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
400
[
{
"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
}
]
}
]
{
"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