Exposing API to third parties for Validating a GSTIN

Documented by : Sanchay Gupta. 5th Feb, 2018

Reviewed by : Shobhit Sharma. 8th Feb, 2018

Customer Use case

While onboarding a Vendor/Customer in my ERP/So ware product, I want to verify the GSTIN number
and therefore avoid any mistakes in invoice prepara on, tax payments and ensure data in systems is
against a valid GSTIN

Customer Benefit
● Never have a wrong GSTIN for your Vendor/Customer in your ERP system/Product Onboarding
● Avoid GST Compliance errors
● Improve overall efficiency by reducing back and forth due to mistakes in GSTINs
● Get Addi onal details

Access to the API

Access to API will be restricted to a security key shared by ClearTax
Base URL: h ps://gst.cleartax.in/api
Header Name: X-Cleartax-Auth-Token
Security Key: Will be provided to the entrerprise

Input
User will provide the input as GSTIN to the API for valida on

API Response
Against a string input, API can have the following responses
1. Response with valid GSTIN input → 200 OK
2. Response with invalid GSTIN input
a. Invalid GSTIN format(regex invalid) → 400 Bad Request
b. Valid GSTIN format, but GSTIN is not exis ng/invalid → 200 OK with empty data
3. Any other System failure → 500 Internal Server Error
a. Failure due to GSTN being non responsive or under Down mes.
b. Failure at ClearTax to connect with third party or GSTN (<0.01% occurrence on 10L
randomly sampled API calls in a month)

Response will have mul ple property fields as below:

Parameter Field Field Present in API

Name Description Specifications Sample Value Response
gstin GSTIN of the Tax Payer String 29HJKPS9689A8Z5 Yes (100%)
lgnm Legal Name of Business String Kamath Foods Yes (100%)
stj State Jurisdic on String Karnataka Yes (~90%)
ctj Centre Jurisdic on String Delhi Yes (~90%)
Date
rgdt Date of Registra on [DD/MM/YYYY] 05/05/2017 Yes (100%)
ctb Cons tu on of Business String sole Yes (~99%)
dty Taxpayer type String Casual Yes (100%)
[ "Bonded Warehouse",
"Factory / Manufacturing",
"Input Service Distributor
(ISD)",
nba Nature of Business Ac vity Array of Strings "Office / Sale Office" ] Yes (~99%)
sts GSTN status String Ac ve Yes
Date
cxdt Date Of Cancella on [DD/MM/YYYY] NA Yes
Date
lstupddt Last Updated Date [DD/MM/YYYY] 01/05/2017 No
stjCd State Jurisdic on Code String AP003 No
ctjCd Centre Jurisdic on Code String AP004 No
tradeNam Trade Name String ALTON PLASTIC PRIVATE LTD. No
adadr Additional Place of Business Fields Array of Strings NA No
addr Additional place of business address Array of Strings NA No
bnm Building Name String NA No
st Street String NA No
loc Loca on String NA No
bno Door Number String NA No
stcd state name String NA No
flno floor nbr String NA No
lt la tude String NA No
lg longitude String NA No
pncd pin code Integer NA No
ntr Nature of Addi onal place of NA
business Array of Strings No
pradr Pricipal Place of Business fields Array of Strings NA No
addr Pricipal Place of Business Address Array of Strings NA No
bnm Building Name String NA No
st Street String NA No
loc Loca on String NA No
bno Door Number String NA No
stcd State name String NA No
flno Floor Number String NA No
lt La tude String NA No
lg Longitude String NA No
pncd Pin Code Integer NA No
ntr Nature of pricipal place of Business String NA No

Detailed API Documentation

Detailed API Documenta on is present below. It can also be viewed on - https://editor.swagger.io/ by
pas ng the contents in the console available on the link

swagger: '2.0'
basePath: /gst
info:
version: '0.0'
tle: ''
tags:
- name: CommonsResource
paths:
/v0.1/common/search_taxpayer:
get:
tags:
- CommonsResource
summary: Search Taxpayer Details By GSTIN
descrip on: ''
opera onId: searchTaxPayerDetails
consumes:
- applica on/json
produces:
- applica on/json
parameters:
- name: gs n
in: query
required: true
type: string
responses:
'200':
 descrip on: Taxpayer Details
schema:
$ref: '#/defini ons/SearchTaxpayerResponse'
'401':
descrip on: Not authorized
defini ons:
SearchTaxpayerResponse:
type: object
proper es:
gs n:
type: string
example: 29AAGCC4236P1Z5
descrip on: GSTIN
lgnm:
type: string
example: CONSULTING ROOMS PRIVATE LIMITED
descrip on: Legal Business Name
stj:
type: string
example: LVO 015 - BENGALURU
descrip on: State Jurisdic on
ctj:
type: string
example: RANGE-III
descrip on: Centre Jurisdic on
rgdt:
type: string
example: 01/07/2017
descrip on: Date Of Registar on
ctb:
type: string
example: Proprietorship
descrip on: Cons tu on Of Business
dty:
type: string
example: Regular
descrip on: TaxPayer Type
nba:
type: array
descrip on: Nature Of Business Ac vity
items:
type: string
sts:
 type: string
example: Ac ve
descrip on: GSTIN Status
cxdt:
type: string
example: 31/12/2017
descrip on: Date of Cancella on