GSTIN Advanced

Endpoint Overview

POST /api/v1/corporate/gstin-advanced

Description

The GSTIN Advanced API provides comprehensive verification and detailed information retrieval for Goods and Services Tax Identification Numbers (GSTINs) in India. This API allows businesses to validate GST registrations, access business details, jurisdictional information, registration status, and other critical compliance data. The advanced version offers enhanced data points including promoter information, annual turnover, e-invoice status, and business activity details that aren't available in standard GSTIN verification services.

Key Benefits

Comprehensive Business Verification: Access complete GSTIN details including business constitution, registration dates, and current status

Enhanced Due Diligence: Verify business legitimacy with promoter details, jurisdictional information, and compliance status

Regulatory Compliance: Ensure partners and vendors have valid GST registrations before conducting business transactions

Rich Data Insights: Obtain detailed business activity information, turnover slabs, and e-invoice eligibility status

Use Cases

Financial Services

Supply Chain

Enterprise Solutions

Verify business legitimacy during customer onboarding for business loans

Conduct enhanced KYC for corporate banking clients

Validate supplier information for invoice financing

Automate business verification for credit risk assessment

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	JWT Bearer token for authentication. Format: `Bearer <your_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	GSTIN Number
fy	String	No	Financial year
filing_status_get	Boolean	No	Get Filing status or not
hsn_info_get	Boolean	No	HSN Info
fallback	Boolean	No	Fallback to normal gstin
filing_frequency_get	Boolean	No	Get Filing frequency
split_address	Boolean	No	Get Address Dictionary
liability_percentage_get	Boolean	No	Get Liability Percentage
skip_fallback	Boolean	No	Skip Fallback

Example Request

{
    "id_number": "27AAACR5055K2Z6"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all the GSTIN verification details
data.contact_details	Object	Contains principal and additional contact information
data.contact_details.principal	Object	Primary contact details including address, email, mobile, and nature of business
data.contact_details.additional	Array	List of additional contact information if available
data.promoters	Array	List of promoters or directors associated with the business
data.annual_turnover	String	Annual turnover slab of the business
data.annual_turnover_fy	String	Financial year for the annual turnover information
data.percentage_in_cash	String	Percentage of transactions conducted in cash
data.aadhaar_validation	String	Whether Aadhaar validation is completed ("Yes" or "No")
data.aadhaar_validation_date	String	Date when Aadhaar validation was completed (YYYY-MM-DD)
data.address_details	Object	Detailed address information
data.einvoice_status	Boolean	Whether the business is eligible for e-invoicing
data.client_id	String	Unique client identifier for the request
data.gstin	String	GSTIN of the business
data.pan_number	String	PAN (Permanent Account Number) of the business
data.business_name	String	Trade name of the business
data.legal_name	String	Legal registered name of the business
data.center_jurisdiction	String	Central tax jurisdiction details
data.state_jurisdiction	String	State tax jurisdiction details
data.date_of_registration	String	Date of GST registration (YYYY-MM-DD)
data.constitution_of_business	String	Legal constitution type of the business
data.taxpayer_type	String	Type of taxpayer (Regular, Composition, etc.)
data.gstin_status	String	Current status of the GSTIN (Active, Inactive, etc.)
data.date_of_cancellation	String	Date of GSTIN cancellation if applicable
data.field_visit_conducted	String	Whether field visit was conducted for verification
data.nature_bus_activities	Array	List of business activities
data.nature_of_core_business_activity_code	String	Code representing core business activity
data.nature_of_core_business_activity_description	String	Description of core business activity
data.filing_status	Array	GST return filing status information
data.hsn_info	Object	Harmonized System of Nomenclature information
data.filing_frequency	Array	Frequency of GST return filings
status_code	Integer	HTTP status code of the response
success	Boolean	Whether the API request was successful
message	String	Additional message information (null if successful)
message_code	String	Code indicating the status of the request

Example Successful Response

{
    "data": {
        "contact_details": {
            "principal": {
                "address": "Building 10A, 5 TTC Industrial Area, Reliance Corporate Park, Thane Belapur Road, Ghansoli, Navi Mumbai, Thane, Maharashtra, 400701",
                "email": "test@ril.com",
                "mobile": "9999999999",
                "nature_of_business": "Recipient of Goods or Services, Supplier of Services, Export, Office / Sale Office, Import"
            },
            "additional": []
        },
        "promoters": [
            "Madhusudana Sivaprasad Panda ",
            "Mukesh Dhirubhai Ambani ",
            "Pawan kumar Kapil ",
            "Nikhil Rasiklal Meswani ",
            "Hital Rasiklal Meswani "
        ],
        "annual_turnover": "Slab: Rs. 500 Cr. and above",
        "annual_turnover_fy": "2023-2024",
        "percentage_in_cash_fy": "",
        "percentage_in_cash": "NA",
        "aadhaar_validation": "Yes",
        "aadhaar_validation_date": "2024-02-17",
        "address_details": {},
        "liability_percentage_details": {},
        "less_info": false,
        "einvoice_status": true,
        "client_id": "corporate_gstin_advanced_fEKcxIupSgRWHibggcvs",
        "gstin": "27AAACR5055K2Z6",
        "pan_number": "AAACR5055K",
        "business_name": "Reliance Industries Limited",
        "legal_name": "Reliance Industries Limited",
        "center_jurisdiction": "State - CBIC,Zone - MUMBAI,Commissionerate - BELAPUR,Division - DIVISION IV,Range - RANGE-IV (Jurisdictional Office)",
        "state_jurisdiction": "State - Maharashtra,Zone - Thane,Division - RAIGAD,Charge - URAN_701",
        "date_of_registration": "2017-06-28",
        "constitution_of_business": "Public Limited Company",
        "taxpayer_type": "Regular",
        "gstin_status": "Active",
        "date_of_cancellation": "1800-01-01",
        "field_visit_conducted": "No",
        "nature_bus_activities": [
            "Recipient of Goods or Services",
            "Supplier of Services",
            "Export",
            "Office / Sale Office",
            "Import"
        ],
        "nature_of_core_business_activity_code": "SPO",
        "nature_of_core_business_activity_description": "Service Provider and Others",
        "filing_status": [],
        "address": null,
        "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. Please provide a valid 15-character GSTIN.",
    "message_code": "invalid_gstin_format"
}

The provided GSTIN is not in the correct format or doesn't pass basic validation checks.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

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

Implement proper error handling to avoid exposing sensitive information

Validate and sanitize the GSTIN input before sending to the API

User Experience Guidelines

Implement caching for frequently accessed GSTINs to improve response times

Display a loading indicator during API calls as verification may take a few seconds

Provide clear error messages to users when verification fails

Format the returned data in a user-friendly way, especially jurisdiction and address information

Implement retry logic with exponential backoff for temporary service unavailability

Code Samples

cURL

Python

Node.js

Related APIs

GSTIN Basic Verification API: Provides basic verification of GSTIN with limited data points

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

Business Verification API: Comprehensive business verification including registration, directors, and financial information

Document OCR API: Extract information from GST certificates and registration documents

Compliance and Legal Considerations

The GSTIN data provided by this API is sourced from government databases and should be used in compliance with applicable laws

Data obtained through this API should be handled in accordance with data protection regulations

The API should not be used for mass scraping of GSTIN data without proper authorization

Businesses should maintain proper records of verifications performed for audit and compliance purposes

Usage of this API for KYC purposes should comply with RBI, SEBI, and other regulatory guidelines

{ "data": { "contact_details": { "principal": { "address": "Building 10A, 5 TTC Industrial Area, Reliance Corporate Park, Thane Belapur Road, Ghansoli, Navi Mumbai, Thane, Maharashtra, 400701", "email": "test@ril.com", "mobile": "9999999999", "nature_of_business": "Recipient of Goods or Services, Supplier of Services, Export, Office / Sale Office, Import" }, "additional": [] }, "promoters": [ "Madhusudana Sivaprasad Panda ", "Mukesh Dhirubhai Ambani ", "Pawan kumar Kapil ", "Nikhil Rasiklal Meswani ", "Hital Rasiklal Meswani " ], "annual_turnover": "Slab: Rs. 500 Cr. and above", "annual_turnover_fy": "2023-2024", "percentage_in_cash_fy": "", "percentage_in_cash": "NA", "aadhaar_validation": "Yes", "aadhaar_validation_date": "2024-02-17", "address_details": {}, "liability_percentage_details": {}, "less_info": false, "einvoice_status": true, "client_id": "corporate_gstin_advanced_fEKcxIupSgRWHibggcvs", "gstin": "27AAACR5055K2Z6", "pan_number": "AAACR5055K", "business_name": "Reliance Industries Limited", "legal_name": "Reliance Industries Limited", "center_jurisdiction": "State - CBIC,Zone - MUMBAI,Commissionerate - BELAPUR,Division - DIVISION IV,Range - RANGE-IV (Jurisdictional Office)", "state_jurisdiction": "State - Maharashtra,Zone - Thane,Division - RAIGAD,Charge - URAN_701", "date_of_registration": "2017-06-28", "constitution_of_business": "Public Limited Company", "taxpayer_type": "Regular", "gstin_status": "Active", "date_of_cancellation": "1800-01-01", "field_visit_conducted": "No", "nature_bus_activities": [ "Recipient of Goods or Services", "Supplier of Services", "Export", "Office / Sale Office", "Import" ], "nature_of_core_business_activity_code": "SPO", "nature_of_core_business_activity_description": "Service Provider and Others", "filing_status": [], "address": null, "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 Advanced

GSTIN Advanced#

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

GSTIN Advanced

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples