FETCH GSTIN NUMBERS FOR A PROVIDED LEGAL ENTITY NAME
Description
This API can be used for a reverse lookup of GSTIN number for a given company name. Since GSTIN numbers and PAN numbers are connected, this API also provides a medium for reverse lookup of PAN Numbers for a given entity name.
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 | Min Version | Max Version |
|---|---|---|---|
POST | https://api.attestr.com/api/{version}/public/corpx/gstin/search | v1 |
Request Body Parameters
Type | Name | Description | Optional (default) | Min Version | Max Version |
|---|---|---|---|---|---|
String | legalName | Input legal entity name to be searched. Max acceptable length is 200 characters. | Required | v1 |
Although the legal name field allows for partial names, it is best to provide the full name of the legal entity in order to get the best results. As the parameter name also implies, this API searches against the entity's legal name rather than its trade names. Therefore, it is best to avoid searching by trade name as it may not produce relevant results.
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 PAN is either invalid or not matching records are found, all keys except valid and message are omitted. If true, remaining keys will have appropriate data.
Key | Description | Type | Min Version | Max Version |
|---|---|---|---|---|
valid | True if the provided legal name is valid and matching GSTIN records exist, else returns false. | Boolean | v1 | |
message | Message if no matching records are found, else null. | String | v1 | |
records | Array of GSTIN Search Record Object. Refer to the definition below. | Array | v1 |
The API returns a maximum of 100 matching records. Names that match more than 100 GSTIN numbers will return only first 100 matching records found in no specific order.
GSTIN Search Record Object
Key | Description | Type | Min Version | Max Version |
|---|---|---|---|---|
status | Status of GST registration, Active, Cancelled etc. | String | 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 | |
type | Regular etc. | String | v1 | |
registered | Date of GSTIN registration DD-MM-YYYY | Date | v1 | |
primaryAddress | Primary registered address of the company. Refer to GST Address Object definition below. | Object | v1 |
GST 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 |
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 output
Sample response for invalid legal name / No matching records
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 |