Init GSTIN Verification

Endpoint Overview

POST /api/v1/corporate-otp/gstin/init

Description

This API endpoint initiates the GSTIN (Goods and Services Tax Identification Number) verification process. It allows you to retrieve comprehensive information about a business entity registered under GST in India, including contact details, business information, registration status, promoters, and financial data. This endpoint serves as the first step in the GSTIN verification workflow, providing essential business verification data for KYC and compliance purposes.

Key Benefits

Instant access to official GST registration data for business verification

Comprehensive business profile including contact details, promoters, and financial information

Verification of business legitimacy through government-registered GST data

Streamlined KYC process for B2B onboarding and compliance requirements

Use Cases

Financial Services

B2B Platforms

Compliance & Risk

Verify business identity during corporate account opening

Validate business details for loan or credit applications

Confirm GST registration status for tax compliance verification

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 (JWT format)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	The GST Number to be verified
hsn_info_get	Boolean	No	Flag to retrieve HSN (Harmonized System of Nomenclature) information
filing_status_get	Boolean	No	Get filling status or not
split_address	Boolean	No	Split Address

Example Request

{
    "id_number": "08ABBCS1438D1ZN",
    "hsn_info_get": true
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the verification data and business details
data.client_id	String	Unique client ID for the verification session
data.email	String	GST holder's email address
data.mobile	String	GST holder's mobile number
data.fallback	Boolean	Indicates if fallback method was used
data.details	Object	Comprehensive business details from GST registration
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code representing the response message

Details Object Structure

Parameter	Type	Description
contact_details	Object	Contains principal and additional contact information
promoters	Array	List of promoters associated with the business
annual_turnover	String	Annual turnover slab of the business
annual_turnover_fy	String	Financial year for the annual turnover
aadhaar_validation	String	Indicates if Aadhaar validation is done
aadhaar_validation_date	String	Date of Aadhaar validation (YYYY-MM-DD)
gstin	String	GSTIN of the business
pan_number	String	PAN number of the business
business_name	String	Registered business name
legal_name	String	Legal name of the business
center_jurisdiction	String	Central tax jurisdiction details
state_jurisdiction	String	State tax jurisdiction details
date_of_registration	String	GST registration date (YYYY-MM-DD)
constitution_of_business	String	Type of business constitution
taxpayer_type	String	Type of taxpayer
gstin_status	String	Current status of the GSTIN
nature_bus_activities	Array	List of business activities
nature_of_core_business_activity_code	String	Code for core business activity
nature_of_core_business_activity_description	String	Description of core business activity

Example Successful Response

{
    "data": {
        "client_id": "gst_otp_fedWdafvBBpblZTofJaw",
        "email": "RIL.MHG@ril.com",
        "mobile": "9900012345",
        "fallback": false,
        "details": {
            "contact_details": {
                "principal": {
                    "address": "Thane Belapur Road, Ghansoli, Navi Mumbai, Thane, Maharashtra, 400701",
                    "email": "RIL.MHG@ril.com",
                    "mobile": "9900012345",
                    "nature_of_business": "Factory / Manufacturing, Retail Business, Input Service Distributor (ISD), Bonded Warehouse, SEZ, Works Contract, Warehouse / Depot, Service Provision, Leasing Business, Office / Sale Office, Recipient of Goods or Services, Wholesale Business, EOU / STP / EHTP"
                },
                "additional": [
                    {
                        "address": "IV, MAKER CHAMBERS, NARIMAN POINT, MUMBAI, Mumbai, Maharashtra, 400021",
                        "email": "RIL.MHG@ril.com",
                        "mobile": "9900012345",
                        "nature_of_business": "Factory / Manufacturing, Retail Business, Input Service Distributor (ISD), Bonded Warehouse, SEZ, Works Contract, Warehouse / Depot, Service Provision, Leasing Business, Office / Sale Office, Recipient of Goods or Services, Wholesale Business, EOU / STP / EHTP"
                    },
                    {
                        "address": "CHEMICAL TERMINAL BOMBAY LTD, PIRPAU INSTALLATION, NEAR BPT PUMP HOUSE, TROMBE, Mumbai, Maharashtra, 400074",
                        "email": "RIL.MHG@ril.com",
                        "mobile": "9900012345",
                        "nature_of_business": "Factory / Manufacturing, Retail Business, Input Service Distributor (ISD), Bonded Warehouse, SEZ, Works Contract, Warehouse / Depot, Service Provision, Leasing Business, Office / Sale Office, Recipient of Goods or Services, Wholesale Business, EOU / STP / EHTP"
                    }
                ]
            },
            "promoters": [
                "Nikhil Rasiklal Meswani ",
                "Hital Rasiklal Meswani ",
                "Mukesh Dhirubhai Ambani ",
                "Madhusudana Sivaprasad Panda "
            ],
            "annual_turnover": "Slab: Rs. 500 Cr. and above",
            "annual_turnover_fy": "2022-2023",
            "percentage_in_cash_fy": "",
            "percentage_in_cash": "NA",
            "aadhaar_validation": "Yes",
            "aadhaar_validation_date": "2024-02-28",
            "address_details": {},
            "liability_percentage_details": {},
            "less_info": false,
            "client_id": null,
            "gstin": "27AAACR1234K1Z7",
            "pan_number": "AAACR1234K",
            "business_name": "RELIANCE INDUSTRIES LIMITED",
            "legal_name": "RELIANCE INDUSTRIES LIMITED",
            "center_jurisdiction": "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-07-01",
            "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": [
                "Factory / Manufacturing",
                "Retail Business",
                "Input Service Distributor (ISD)",
                "Bonded Warehouse",
                "SEZ",
                "Works Contract",
                "Warehouse / Depot",
                "Service Provision",
                "Leasing Business",
                "Office / Sale Office",
                "Recipient of Goods or Services",
                "Wholesale Business",
                "EOU / STP / EHTP",
                "Supplier of Services",
                "Others",
                "Export"
            ],
            "nature_of_core_business_activity_code": "MFT",
            "nature_of_core_business_activity_description": "Manufacturer",
            "filing_status": [],
            "address": null,
            "hsn_info": {},
            "filing_frequency": []
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid GSTIN

Authentication Error

Service Unavailable

{
    "status_code": 400,
    "success": false,
    "message": "Invalid GSTIN format",
    "message_code": "invalid_gstin"
}

The provided GSTIN is not in the correct format or does not exist.

Integration Best Practices

Security Recommendations

Store API keys 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

Implement IP whitelisting for additional security when accessing the API

User Experience Guidelines

Implement proper validation of GSTIN format before making API calls

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

Provide clear error messages to users when verification fails

Store the client_id securely for subsequent API calls in the verification flow

Code Samples

cURL

Python

Node.js

Related APIs

GSTIN OTP Verification: Verifies the OTP sent to the registered mobile/email of the GST holder

GSTIN Document Download: Downloads GST registration certificate and other documents

PAN Verification: Verifies PAN details for business and individual verification

Company Verification: Retrieves comprehensive company information from MCA records

Compliance and Legal Considerations

The data retrieved through this API is sourced from government GST records and should be used in compliance with applicable data protection laws. The API should only be used for legitimate business purposes such as KYC, verification, and compliance. Ensure you have appropriate consent before storing or processing the data retrieved through this API.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/corporate-otp/gstin/init' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "08ABBCS1438D1ZN", "hsn_info_get": true }'

{ "data": { "client_id": "gst_otp_fedWdafvBBpblZTofJaw", "email": "RIL.MHG@ril.com", "mobile": "9900012345", "fallback": false, "details": { "contact_details": { "principal": { "address":"Thane Belapur Road, Ghansoli, Navi Mumbai, Thane, Maharashtra, 400701", "email": "RIL.MHG@ril.com", "mobile": "9900012345", "nature_of_business": "Factory / Manufacturing, Retail Business, Input Service Distributor (ISD), Bonded Warehouse, SEZ, Works Contract, Warehouse / Depot, Service Provision, Leasing Business, Office / Sale Office, Recipient of Goods or Services, Wholesale Business, EOU / STP / EHTP" }, "additional": [ { "address": "IV, MAKER CHAMBERS, NARIMAN POINT, MUMBAI, Mumbai, Maharashtra, 400021", "email": "RIL.MHG@ril.com", "mobile": "9900012345", "nature_of_business": "Factory / Manufacturing, Retail Business, Input Service Distributor (ISD), Bonded Warehouse, SEZ, Works Contract, Warehouse / Depot, Service Provision, Leasing Business, Office / Sale Office, Recipient of Goods or Services, Wholesale Business, EOU / STP / EHTP" }, { "address": "CHEMICAL TERMINAL BOMBAY LTD, PIRPAU INSTALLATION, NEAR BPT PUMP HOUSE, TROMBE, Mumbai, Maharashtra, 400074", "email": "RIL.MHG@ril.com", "mobile": "9900012345", "nature_of_business": "Factory / Manufacturing, Retail Business, Input Service Distributor (ISD), Bonded Warehouse, SEZ, Works Contract, Warehouse / Depot, Service Provision, Leasing Business, Office / Sale Office, Recipient of Goods or Services, Wholesale Business, EOU / STP / EHTP" } ] }, "promoters": [ "Nikhil Rasiklal Meswani ", "Hital Rasiklal Meswani ", "Mukesh Dhirubhai Ambani ", "Madhusudana Sivaprasad Panda " ], "annual_turnover": "Slab: Rs. 500 Cr. and above", "annual_turnover_fy": "2022-2023", "percentage_in_cash_fy": "", "percentage_in_cash": "NA", "aadhaar_validation": "Yes", "aadhaar_validation_date": "2024-02-28", "address_details": {}, "liability_percentage_details": {}, "less_info": false, "client_id": null, "gstin": "27AAACR1234K1Z7", "pan_number": "AAACR1234K", "business_name": "RELIANCE INDUSTRIES LIMITED", "legal_name": "RELIANCE INDUSTRIES LIMITED", "center_jurisdiction": "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-07-01", "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": [ "Factory / Manufacturing", "Retail Business", "Input Service Distributor (ISD)", "Bonded Warehouse", "SEZ", "Works Contract", "Warehouse / Depot", "Service Provision", "Leasing Business", "Office / Sale Office", "Recipient of Goods or Services", "Wholesale Business", "EOU / STP / EHTP", "Supplier of Services", "Others", "Export" ], "nature_of_core_business_activity_code": "MFT", "nature_of_core_business_activity_description": "Manufacturer", "filing_status": [], "address": null, "hsn_info": {}, "filing_frequency": [] } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Init

Init GSTIN Verification#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Details Object Structure#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses