GSTIN Verification API

Endpoint Overview

POST /api/v1/corporate/gstin

Description

The GST Verification API allows you to verify and retrieve comprehensive information about businesses registered under India's Goods and Services Tax (GST) system. By providing a valid GSTIN (GST Identification Number), you can access detailed business information including registration status, business details, jurisdictional information, and tax compliance data.

This API performs real-time validation against official GST databases to ensure the information returned is accurate and up-to-date, making it ideal for KYC processes, vendor verification, and regulatory compliance checks.

Key Benefits

Instant Verification: Validate GST registration status in real-time

Comprehensive Business Details: Access complete business information including legal name, address, and business type

Compliance Insights: View registration dates, filing status, and jurisdictional information

Fraud Prevention: Verify business legitimacy before entering into commercial relationships

Use Cases

Financial Services

E-commerce

Enterprise

Verify business identity during customer onboarding

Validate vendor GST details before processing payments

Automate KYC/KYB processes for business accounts

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication. Format: `Bearer YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	The GSTIN (Goods and Services Tax Identification Number) to verify. Must be a valid 15-character GSTIN.

Example Request

{
    "id_number": "08AKWPJ1234H1ZN"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for all the GSTIN verification data
data.address_details	Object	Detailed address information of the business
data.client_id	String	Unique identifier for the client making the request
data.gstin	String	The verified GSTIN of the business
data.pan_number	String	PAN (Permanent Account Number) of the business
data.business_name	String	Trading name of the business entity
data.legal_name	String	Legal registered name of the business owner or entity
data.center_jurisdiction	String	Central tax jurisdiction details
data.state_jurisdiction	String	State tax jurisdiction details
data.date_of_registration	String	Date when the business was registered for GST (YYYY-MM-DD)
data.constitution_of_business	String	Legal structure of the business (e.g., Proprietorship, Partnership)
data.taxpayer_type	String	Category of taxpayer (Regular, Composition)
data.gstin_status	String	Current status of the GSTIN (Active, Inactive)
data.date_of_cancellation	String	Date when GSTIN was cancelled, if applicable (YYYY-MM-DD)
data.field_visit_conducted	String	Whether a field visit was conducted for verification (Yes, No)
data.nature_bus_activities	Array	List of business activities the entity is engaged in
data.nature_of_core_business_activity_code	String	Code representing the primary business activity
data.nature_of_core_business_activity_description	String	Description of the primary business activity
data.aadhaar_validation	String	Whether Aadhaar validation was completed (Yes, No)
data.aadhaar_validation_date	String	Date of Aadhaar validation (YYYY-MM-DD)
data.filing_status	Array	GST return filing status information
data.address	String	Complete business address as a single string
data.hsn_info	Object	Information related to HSN (Harmonized System of Nomenclature) codes
data.filing_frequency	Array	Frequency of GST return filing
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API request was successful
message	String	Additional information about the response (null if successful)
message_code	String	Code indicating the status of the response

Example Successful Response

{
    "data": {
        "address_details": {},
        "client_id": "corporate_gstin_hemuprVyNGvtQAvRJHXy",
        "gstin": "08AKWPJ1234H1ZN",
        "pan_number": "AKWPJ1234H",
        "business_name": "MINDA MARWAR PRODUCER COMPANY",
        "legal_name": "MADAN LAL JAT",
        "center_jurisdiction": "Commissionerate - JODHPUR,Division - GST DIVISION",
        "state_jurisdiction": "State - Rajasthan,Zone",
        "date_of_registration": "2021-10-20",
        "constitution_of_business": "Proprietorship",
        "taxpayer_type": "Regular",
        "gstin_status": "Active",
        "date_of_cancellation": "1800-01-01",
        "field_visit_conducted": "No",
        "nature_bus_activities": [
            "Retail Business",
            "Wholesale Business"
        ],
        "nature_of_core_business_activity_code": "NA",
        "nature_of_core_business_activity_description": "NA",
        "aadhaar_validation": "Yes",
        "aadhaar_validation_date": "2021-10-20",
        "filing_status": [],
        "address": "MINDA NAVA, WARD NO. 15, VILL. BHEEVPURA",
        "hsn_info": {},
        "filing_frequency": []
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid GSTIN

GSTIN Not Found

Authentication Error

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid GSTIN format",
    "message_code": "invalid_input"
}

The provided GSTIN is not in the correct format. A valid GSTIN consists of 15 characters.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications to ensure data encryption in transit

Rotate JWT tokens periodically and implement token expiration policies

Implement IP whitelisting for additional security if supported by your infrastructure

User Experience Guidelines

Implement client-side GSTIN format validation before making API calls

Display a loading indicator during API calls to provide feedback to users

Cache verified GSTIN data (where appropriate) to reduce redundant API calls

Provide clear error messages to users when verification fails

Format returned business details in a user-friendly, readable format

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API: Verify Permanent Account Number details for individuals and businesses

Business Registration Verification API: Verify company registration details with MCA

Bank Account Verification API: Verify bank account details for businesses

Address Verification API: Verify business address details

Compliance and Legal Considerations

The use of this API must comply with applicable data protection laws in India

Ensure you have appropriate consent before verifying business information

GST data should be handled securely and in accordance with privacy regulations

The API should not be used for unauthorized surveillance or monitoring of businesses

Data retrieved through this API should be used only for legitimate business purposes

{ "data": { "address_details": {}, "client_id": "corporate_gstin_hemuprVyNGvtQAvRJHXy", "gstin": "08AKWPJ1234H1ZN", "pan_number": "AKWPJ1234H", "business_name": "MINDA MARWAR PRODUCER COMPANY", "legal_name": "MADAN LAL JAT", "center_jurisdiction": "Commissionerate - JODHPUR,Division - GST DIVISION", "state_jurisdiction": "State - Rajasthan,Zone", "date_of_registration": "2021-10-20", "constitution_of_business": "Proprietorship", "taxpayer_type": "Regular", "gstin_status": "Active", "date_of_cancellation": "1800-01-01", "field_visit_conducted": "No", "nature_bus_activities": [ "Retail Business", "Wholesale Business" ], "nature_of_core_business_activity_code": "NA", "nature_of_core_business_activity_description": "NA", "aadhaar_validation": "Yes", "aadhaar_validation_date": "2021-10-20", "filing_status": [], "address": "MINDA NAVA, WARD NO. 15, VILL. BHEEVPURA", "hsn_info": {}, "filing_frequency": [] }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

GSTIN

GSTIN Verification API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses