Search GSTIN By PAN Number API
FETCH GST REGISTERED ENTITIES MAPPED TO A PROVIDED PAN NUMBER
Description
Many businesses with multiple locations or those involved in multiple commercial services have multiple GSTINs registered. GSTIN numbers are linked to PAN, the permanent account number assigned to each entity by the Income Tax Department of India. As a result, a single PAN number might frequently be connected to numerous GSTIN numbers.
Such registered multiple GST numbers linked to a given PAN number can be searched using this API.
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 | pan | Input PAN number to be searched. | Required | v1 |
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
{ "pan": "AHCCC1234R"}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 PAN 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. PAN numbers that are linked to more than 100 GSTIN 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
{ "valid": true, "message": null, "records": [ { "gstin": "07ABCDE0405F1ZW", "active": true, "pan": "ABCDE0405F", "registered": "12-07-2018", "legalName": "TIMES XXXXX XXXXX LIMITED", "tradeName": "XXXXX XXXXX", "status": "Active", "type": "Regular", "constitution": "Public Limited Company", "primaryAddress": { "type": "PRIMARY", "building": "601,GD-ITL,NORTHEX TOWER", "buildingName": "NETAJI SHUBHASH PLACE", "floor": "A-09", "street": "PITAMPURA", "locality": "DELHI", "district": "West Delhi", "city": "", "state": "Delhi", "zip": "110034", "latitude": "", "longitude": "", "nature": "Supplier of Services, Wholesale Business" } } ]}Sample response for invalid PAN / No matching records
{ "valid": false, "message": "No matching records found"}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
{ "code": 4001, "message": "Malformed data or missing required parameter values"}