GSTIN Verification Basic

❗️ This API Documentation is now available in Clear Identity Demo hub here

---

Clear provides APIs to verify if a GSTIN is valid as per the Government. This will help you to:

• Prevent wrong/incorrect GSTINs of vendors or customers in ERP

• Avoid GST compliance errors

• Get additional details related to the GSTIN

Request Method

GET

Request URL

{BASE_URL}/clearIdentity/v1/taxpayer-info

Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	NA	Mandatory. User auth token

Request Path Params

There are no path parameters for this API.

Request Query Params

Parameter	Data Type	Field Validations
gstin	String	MaxLength: 15 Regex: Valid GSTIN as per government.	Mandatory. The GSTIN that you want the information for.

Request Body

There will be no request body for this API.

Sample Request

https://api-sandbox.clear.in/clearIdentity/v1/taxpayer-info?gstin=29AAFCD5862R1ZR

Response Status Codes

HTTP Status Code	Description
200	OK
400	Bad Request
401	Authorisation failed
402	Payment Required
429	Too many requests
500	Service is down

Response Schema

Parameter	Data Type	Field Constraints	Description
taxpayerInfo	Object	NA	Mandatory. Taxpayer Information Object. If there is no value, this will be null.
requestId	String	MaxLength: 36	Mandatory. Unique identifier generated by Clear to trace any request. Users can share this while raising support cases. If there is no value, this will be an empty string.

Taxpayer Info Object

Parameter	Data Type	Field Constraints	Description
gstin	String	MaxLength: 15	Mandatory. GSTIN of the Taxpayer. If there is no value, this will be an empty string.
pan	String	MaxLength: 10	Mandatory, PAN of the Taxpayer. If there is no value, this will be an empty string.
legalBusinessName	String	MaxLength: 255	Mandatory - Legal Name of the Taxpayer. If there is no value, this will be an empty string.
tradeName	String	MaxLength: 255	Mandatory - Trade Name of the Taxpayer. If there is no value, this will be an empty string.
taxpayerType	String	MaxLength: 255	Mandatory -Taxpayer Type. If there is no value, this will be null. The common values this field include the following. But these are subject to additions and modifications by the government portal: Casual Taxable Person Composition Consulate or Embassy of Foreign Country Input Service Distributor (ISD) Non Resident Online Services Provider Non Resident Taxable Person Other Notified Person Regular SEZ Developer SEZ Unit Tax Collector (Electronic Commerce Operator) Tax Deductor United Nation Body
status	String	Enum: Active, Cancelled,Suspended, Provisional	Mandatory - Current Status of the GSTIN. If there is no value, this will be null.
registrationDate	String	Format: dd/mm/yyyy	Mandatory - Date of Registration. If there is no value, this will be an empty string.
cancellationDate	String	Format : dd/mm/yyyy	Conditional - Returned only if the GSTIN is canceled. Date of Cancellation. If there is no value, this will be an empty string.
stateJurisdiction	String	MaxLength: 255	Mandatory - State Jurisdiction. If there is no value, this will be an empty string.
centralJurisdiction	String	MaxLength: 255	Mandatory - Central Jurisdiction. If there is no value, this will be an empty string.
stateJurisdictionCode	String	MaxLength: 255	Mandatory - State Jurisdiction Code. If there is no value, this will be an empty string.
centralJurisdictionCode	String	MaxLength: 255	Mandatory - Central Jurisdiction Code. If there is no value, this will be an empty string.
natureOfBusinessActivity	Array of Strings	NA	Mandatory - Nature of Business Activity. If there is no value, this will be an empty array.
constitutionOfBusiness	String	MaxLength: 255	Mandatory - Constitution of Business. If there is no value, this will be an empty string.
principalAddress	Object	NA	Mandatory - Principal Place of Taxpayer. Address Wrapper Object. If there is no value, this will be null.
additionalAddresses	Array	NA	Optional - Additional Place of Taxpayer. Array of Address Wrapper objects. If no additional addresses are present, then this will be an empty array.
frequencyType	String	Enum: MONTHLY, QUARTERLY	Mandatory - Filing frequency. If there is no value, this will be null.

Address Wrapper Object

Parameter	Data Type	Field Constraints	Description
address	Object	NA	Mandatory - Address object. If there is no value, this will be null.
natureOfBusiness	String	MaxLength: 255	Optional - Nature of Business. If there is no value, this will be an empty string.

Address Object

Parameter	Data Type	Field Constraints	Description
buildingName	String	MaxLength: 255	Optional - Building Name. If there is no value, this will be an empty string.
street	String	MaxLength: 255	Optional - Street. If there is no value, this will be an empty string.
locality	String	MaxLength: 255	Optional - Locality. If there is no value, this will be an empty string.
doorNumber	String	MaxLength: 255	Optional - Door Number. If there is no value, this will be an empty string.
stateName	String	MaxLength: 255	Mandatory - State Name. If there is no value, this will be an empty string.
floorNumber	String	MaxLength: 255	Optional - Floor Number. If there is no value, this will be an empty string.
latitude	String	MaxLength: 255	Optional - Latitude. If there is no value, this will be an empty string.
longitude	String	MaxLength: 255	Optional - Longitude. If there is no value, this will be an empty string.
district	String	MaxLength: 255	Optional - District. If there is no value, this will be an empty string.
city	String	MaxLength: 255	Optional - City. If there is no value, this will be an empty string.
pincode	String	MaxLength: 255	Optional - Pincode. If there is no value, this will be an empty string.

Sample Response (Success)

1) Active GSTIN

Metered: Yes

HTTP Status Code: 200

Response Body

{
    "requestId": "8b422ca6-f3c0-4bf5-89c2-aa8c2717ab98",
    "taxpayerInfo": {
        "gstin": "29AAFCD5862R1ZR",
        "pan": "AAFCD5862R",
        "legalBusinessName": "DEFMACRO SOFTWARE PRIVATE LIMITED",
        "tradeName": "DEFMACRO SOFTWARE PRIVATE LIMITED",
        "taxpayerType": "Regular",
        "status": "Active",
        "registrationDate": "01/07/2017",
        "cancellationDate": "",
        "stateJurisdiction": "LGSTO 016- Bengaluru",
        "centralJurisdiction": "RANGE-ASD7",
        "stateJurisdictionCode": "KA004",
        "centralJurisdictionCode": "YV0701",
        "natureOfBusinessActivity": [
            "Leasing Business",
            "Supplier of Services",
            "Recipient of Goods or Services",
            "Import"
        ],
        "constitutionOfBusiness": "Private Limited Company",
        "principalAddress": {
            "address": {
                "buildingName": "Block 1",
                "street": "HOSUR MAIN ROAD",
                "locality": "BANGALORE",
                "doorNumber": "23, 24 AMR TECH PARK",
                "stateName": "Karnataka",
                "floorNumber": "First Floor",
                "latitude": "",
                "longitude": "",
                "district": "Bengaluru Urban",
                "city": null,
                "pincode": "560068"
            },
            "natureOfBusiness": "Leasing Business, Supplier of Services, Recipient of Goods or Services, Import"
        },
        "additionalAddresses": [],
        "frequencyType": "MONTHLY"
    }
}

2) Cancelled GSTIN

Metered: Yes

HTTP Status Code: 200

Response Body

{
    "requestId": "1024980a-b49d-4602-af30-4a9485be0427",
    "taxpayerInfo": {
        "gstin": "29AQTPN8195L1ZJ",
        "pan": "AQTPN8195L",
        "legalBusinessName": "ROHIT NARWARE",
        "tradeName": "DAILY EAT- KITCHEN",
        "taxpayerType": "Regular",
        "status": "Cancelled",
        "registrationDate": "06/11/2019",
        "cancellationDate": "01/10/2022",
        "stateJurisdiction": "LGSTO 015 - Bengaluru",
        "centralJurisdiction": "RANGE-DED1",
        "stateJurisdictionCode": "KA003",
        "centralJurisdictionCode": "YT0104",
        "natureOfBusinessActivity": [
            "Supplier of Services"
        ],
        "constitutionOfBusiness": "Proprietorship",
        "principalAddress": {
            "address": {
                "buildingName": "MUNIYAPPA COMPOUND",
                "street": "100 FEET RING ROAD,OPP.HDFC BANK, VIVEK NAGAR POST",
                "locality": "BENGALURU",
                "doorNumber": "NO. 35",
                "stateName": "Karnataka",
                "floorNumber": "GROUND FLOOR",
                "latitude": "",
                "longitude": "",
                "district": "Bengaluru Urban",
                "city": "",
                "pinCode": "560047"
            },
            "natureOfBusiness": "Supplier of Services"
        },
        "additionalAddresses": [],
        "frequencyType": null
    }
}

Sample Response (Error)

1) Invalid GSTIN

Metered: Yes

HTTP Status Code: 404

Response Body

{
    "errors": [
        {
            "error_code": "IDEN-005",
            "error_message": "GSTIN - 23AAFCD5862R1ZR is not valid and not present in government records ",
            "error_source": "TP",
            "error_resolution": "Please give a valid GSTIN that’s existing"
        }
    ]
}

2) Incorrect GSTIN (Regex failure)

Metered: No

HTTP Status Code: 400

Response Body

{
    "errors": [
        {
            "error_code": "IDEN-006",
            "error_message": "GSTIN - 23AAFCD5862R1Z is not a 15 char valid GSTIN ",
            "error_source": "CT",
            "error_resolution": "Please give a valid 15 char GSTIN"
        }
    ]
}

3) Invalid Auth Token

Metered: No

HTTP Status Code: 401

Response Body

{
    "errors": [
        {
            "error_code": "IDEN-001",
            "error_message": "Authorisation failed for given authToken",
            "error_source": "CT",
            "error_resolution": "Please provide a valid authToken"
        }
    ]
}

4) Verification service is down

Metered: No

HTTP Status Code: 500

Response Body

{
    "errors": [
        {
            "error_code": "IDEN-007",
            "error_message": "Unable to process Request at the moment. Please try again Later",
            "error_source": "CT",
            "error_resolution": "Contact cleartax support if issue persists."
        }
    ]
}

5) Usage increased

Metered: No

HTTP Status Code: 402

Response Body

{
    "errors": [
        {
            "error_code": "IDEN-002",
            "error_message": "API usage limit has reached threshold",
            "error_source": "CT",
            "error_resolution": "Get threshold limit increased for given API"
        }
    ]
}

6) Too many requests

Metered: No

HTTP Status Code: 429

Response Body

{
    "errors": [
        {
            "error_code": "IDEN-003",
            "error_message": "Requests exceeded rate limit",
            "error_source": "CT",
            "error_resolution": "Ensure calls per minute are within the specified range"
        }
    ]
}

API Validations

Currently there are no known validations.

API Constraints

Licensing and metering against resource : GSTIN_VERIFICATION_CREDITS - If user exceeds the API threshold they would get an error 406.