GSTIN Verification API

VERIFICATION OF GOODS AND SERVICE TAX (GST) REGISTRATION OF BUSINESSES

Description

Indian Goods And Service Tax Act was implemented in July 2017 which replaced many indirect taxes. GSTIN is a unique number assigned to companies registered under this Act.

GSTIN verification is the process of verifying the registration of an entity. Businesses can perform this check as a mandatory taxation compliance while on-boarding new vendors, partners or customer entities.

API Outcome

General company information

Registration status, Entity's registered legal name, Trade / business name, Type of company (private limited, proprietorship etc.), Nature of business

Demographics

Primary address location, Additional locations of business

Timeline

Date of registration, Last updated, Expiration (if applicable)

Jurisdiction

GST Zonal Office of registration and code, Centre name and code

Filing History

Filing date, Period, ARN number, Status of filing

Get Free Trial

Create a free account Or “Talk to Us” for price information and other queries.

Talk to us Create free account

API Details

Request

Type	URL	Current Version
POST	`https://api.attestr.com`/api/{version}/public/corpx/gstin	v2

Request Body Parameters

Type	Name	Description	Optional (default)	Min Version
String	gstin	Input GSTIN	Required	v1
Boolean	fetchFilings	Fetch returns or not	Required	v1
String	fy	Financial year for which returns should be fetched. e.g. 2017-18	Optional (Required if fetch returns input parameter is set to true)	v1

As GST was implemented in 2017, the allowed "fy" parameter values range from 2017-18 till current fiscal year. Values smaller than 2017-18 and greater than current fiscal year will throw malformed request error.

Request Header Parameters

Type	Name	Value / Description	Optional	Min Version	Max Version
String	Content-Type	application/json	Required	v1
String	Authorization	Basic `{authToken}`	Required	v1

If you do not have the authentication token, please refer to Register App to generate one.

Sample Request

JSON
    
 
{  "gstin": "36AAJCPXXXXA1ZQ",  "fetchFilings": true,  "fy": "2018-19"}
Copy

Response

HTTP status code 200

Please note that the valid key decides the availability of rest of the keys in the response. If provided GSTIN is invalid, all keys except valid and message are omitted. If true, remaining keys will have appropriate data.

The GST verification API output now includes the PAN number of the entity. Please refer to the updated schema below.

Key	Description	Type	Min Version
valid	True \| false depending on if the provided tax identification number is valid.	Boolean	v1
active	True \| false implying if the registration status is active	Boolean	v1
legalName	Name of entity as registered in GST database	String	v1
tradeName	Business / trade name as registered in GST database	String	v1
pan	PAN number as extracted from GSTIN.	String	v1
constitution	Constitution type such as private limited, proprietorship etc.	String	v1
nature	Nature of business e.g. supplier of services etc.	Array (String)	v1
type	Regular etc.	String	v1
registered	Date of GSTIN registration DD-MM-YYYY	Date	v1
updated	Date of last change made DD-MM-YYYY	Date	v1
expiry	Date of cancellation if applicable DD-MM-YYYY	Date	v1
state	Zone as defined by GST council	String	v1
stateCode	Zone code	String	v1
center	Office / center in the allotted zone	String	v1
centerCode	Office code	String	v1
addresses	Array of registered primary and additional addresses of the company	Array of Address object	v1
filings	Array of GSTR filings made by the company	Array of GSTFiling object	v1
einvoiceEnabled	Whether the company has opted for e-invoicing. Available from API version v2 onwards.	Boolean	v2
message	Message if the provided GSTIN is valid (available only if valid is false)	String	v1

returns key is not available in the response if the value of input parameter fetchFilings is provided as false.

Address Object

Key	Description	Type	Min Version
type	Type of address	AddressTypeEnum	v1
building	Building, house, plot number	String	v1
buildingName	Name of the premises	String	v1
floor	Floor number in the building	String	v1
street	Name of the street	String	v1
locality	Local area name	String	v1
district	District name	String	v1
state	State name	String	v1
city	City name	String	v1
zip	Pincode of the location	String	v1
latitude	Latitude of the location	String	v1
longitude	Longitude of the location	String	v1
nature	Business purpose for which this address is used	String	v1

GSTFiling Object

Key	Description	Type	Min Version
mode	Online, Offline	String	v1
type	Type of GSTR e.g. GSTR3B, GSTR2, GSTR1 etc.	String	v1
filed	Date of filing of this return MM-DD-YYYY	Date	v1
period	Duration / Month for which filing was made	String	v1
ack	Acknowledgement number	String	v1
status	Filed, Pending payment etc.	String	v1

AddressTypeEnum

Enum Values	Description
PRIMARY	Address is registered as primary registered address
ADDITIONAL	Address is registered as secondary / other addresses of business

Sample Response

Sample response for valid GSTIN

JSON
    
 
{
    "valid": true,    "active": true,    "legalName": "******** IT SOLUTIONS PRIVATE LIMITED",    "tradeName": "******** IT SOLUTIONS PRIVATE LIMITED",    "pan": "AHBHJ5367H",    "constitution": "Private Limited Company",    "nature": [...],
    "type": "Regular",    "registered": "06-12-2019",    "updated": "12-19-2019",    "expiry": null,    "state": "Noida Sector-10",    "stateCode": "UP1587",    "center": "RANGE - 12",    "centerCode": "YC0302",    "addresses": [...],
    "filings": [...],
    "einvoiceEnabled": true}
Copy

Sample response for invalid GSTIN

JSON
    
 
{    "valid": false,    "message": "Provided GSTIN is invalid"}
Copy

Error Response

Parameter	Type	Description
code	Number	Unique error codes for different errors. Always available.
message	String	Error message describing the error. Always Available.
details	String	Detail error message. Available only for certain types of errors.

Error Codes

HTTP Status	Error Code	Error Message
400	4001	Malformed data or missing required parameter values
400	4005	Operation could not be performed due to low credits balance
401	4016	Invalid client authorization
403	4031	Unauthorized access
403	4035	Requested service is not provisioned for your account
403	4039	Client's IP address is not whitelisted
403	4035	Requested service is not provisioned for your account
429	4291	Maximum account rate limit exceeded
429	4292	Maximum API rate limit exceeded
429	4293	Maximum account daily limit exceeded
429	4294	Maximum API daily limit exceeded
500	5001	Request could not be processed

Sample Error Response

JSON
    
 
{  "code": 4001,  "message": "Malformed data or missing required parameter values"}
Copy

Get Free Trial

Create a free account Or “Talk to Us” for price information and other queries.

Talk to us Create free account

Last updated on