Search GSTIN By Company Name API

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.

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 `{authToken}`	Required	v1

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

Sample Request

JSON
    
 
{  "legalName": "Pegadroid IQ Solutions Private Limited"}
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 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
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
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
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

JSON
    
 
{    "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"            }        }    ]}
Copy

Sample response for invalid legal name / No matching records

JSON
    
 
{    "valid": false,    "message": "No matching records found"}
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

Last updated on