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
In order to ensure continued compliance with the Digital Personal Data Protection Act, 2023 (DPDP Act), we are implementing DPDP V3 (Consent-Driven Processing). Under this framework, clients are required to obtain explicit, informed, and verifiable consent from the data principal prior to accessing, processing, viewing, or storing any personal data through the platform. This regulatory transition may require modifications to existing configurations and workflows. Clients are advised to review and update their implementations to ensure ongoing compliance with applicable data protection obligations. Further information regarding this transition can be enquired here. Learn more about this change here.
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 | Max 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 | Required | v1 |
If you do not have the authentication token, please refer to Register App to generate one.
Sample Request
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 | Max 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 | Max 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 | Max 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
Sample response for invalid GSTIN
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 |