GST Verification API
Popular
Check a GSTIN and read the registration details recorded against it. Your onboarding, procurement and credit teams then work from a business identity someone has actually verified.
Overview
GST verification means checking a Goods and Services Tax Identification Number and reading the registration details recorded against it. You may need it before you onboard a merchant, add a vendor to a supplier master, release a payment or assess credit. Each of those decisions needs a GSTIN that exists, belongs to the counterparty in front of you and is active. An API lets you run the check inside the application where the decision happens. You stop looking up every business by hand. Basic returns the registration profile. Advanced adds the filing and return-status information held for the registration, which matters when your decision depends on how regularly a counterparty files. The fields you get back vary by data source and by the individual record. The depth you can call depends on the service contract you agree with us.
- Category
- Tax & Compliance Services
- Coverage
- GST registrations across Indian states and union territories
- Input
- GSTIN
- Output
- The registration details available, plus filing and return-status information at the Advanced depth
- Typical users
- Lenders, marketplaces, payment platforms, insurers, procurement and vendor onboarding teams
- Coverage note
- Registrations issued across Indian states and union territories. Available fields vary by data source and by record.
The overview and the sections after the reference are the FinSour API catalog’s own record for this service, rendered unaltered.
Endpoint URL and method
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Authentication
Send your API key in this header on every call, from your own server: a key sent from a browser is refused. A key starting fs_test_ calls the sandbox and one starting fs_live_ calls production, at the same address. Create keys in the FinSour console.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Request parameters
Headers
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
Idempotency-Key | string | Required | A key you generate for each attempt. Sending the same key again returns the first answer instead of running the check twice; the same key with a different body is refused. | 8 to 255 characters. Matches ^[A-Za-z0-9._:-]+$ |
Body
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
input | object | Required | The details to check. | — |
input. | string | Required | — | Matches ^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]Z[0-9A-Z]$. Exactly 15 characters |
options | object | Optional | Settings for this call. | — |
options. | string | Optional | Your own reference for this call. It comes back unchanged as meta.reference. | 1 to 128 characters |
options. | object | Optional | The person's consent to this check. | — |
options. | boolean | Required | Send true once the person has agreed to the check. | Always true |
options. | string (date-time) | Required | When the person gave consent. | — |
options. | string | Required | What the check is for, for example kyc. | 1 to 64 characters |
Request samples
cURL
curl -X POST https://gateway.staging.finsour.io/v1/business/gstin \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"input": {
"gstin": "<gstin>"
}
}'Node.js
const response = await fetch("https://gateway.staging.finsour.io/v1/business/gstin", {
method: "POST",
headers: {
"X-Api-Key": process.env.FINSOUR_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"input": {
"gstin": "<gstin>"
}
}),
});
console.log(response.status, await response.json());Python
import os
import uuid
import requests
response = requests.post(
"https://gateway.staging.finsour.io/v1/business/gstin",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"input": {
"gstin": "<gstin>",
},
},
timeout=30,
)
print(response.status_code, response.json())Generated from the fields above. Replace each value in angle brackets with your own; the key is read from FINSOUR_API_KEY.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Response schema
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
data | object | Always | The result of the check. | — |
data. | boolean | Always | — | — |
data. | string | Always | — | Matches ^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]Z[0-9A-Z]$. Exactly 15 characters |
data. | string or null | Always | The taxpayer's legal name; for a proprietorship, the proprietor's own. Whole here; Finsour keeps only partial letters of it. | — |
data. | string or null | Always | The name the business trades under. | — |
data. | string or null | Always | The registration's status word (for example ACTIVE, CANCELLED), upper-cased, as given. | — |
data. | string or any or null | Always | — | — |
data. | string or any or null | Always | The day the registration was cancelled; null for one that has not been. | — |
data. | string or null | Always | The constitution of the business (for example PRIVATE LIMITED COMPANY), upper-cased, as given. | — |
data. | string or null | Always | The taxpayer type (for example REGULAR), upper-cased, as given. | — |
data. | array of strings | Always | Every nature of business the registration names, as given. | — |
data. | object or any or null | Always | — | — |
data. | array of objects | Always | — | — |
data. | array of strings | Always | What the place is used for, one entry each (for example Warehouse / Depot). | — |
data. | object or any or null | Always | — | — |
data. | string or null | Always | The whole address on one line, as the registry prints it (Release 1.1). | — |
data. | number or null | Always | The place's latitude in decimal degrees, as the registry publishes it (Release 1.1). | Minimum -90. Maximum 90 |
data. | number or null | Always | The place's longitude in decimal degrees (Release 1.1). | Minimum -180. Maximum 180 |
data. | string or any or null | Always | When the registry last updated this place (Release 1.1). | — |
data. | object or any or null | Always | The place's own e-mail and mobile number, as the registry records them (Release 1.1). Returned live and never stored. | — |
data. | object or any or null | Always | — | — |
data. | object or any or null | Always | — | — |
data. | boolean or null | Always | Whether the taxpayer is enabled for e-invoicing. | — |
data. | string or any or null | Always | — | — |
data. | object | Always | — | — |
data. | string | Always | When the answer was fetched: RFC 3339 UTC with a Z, never an epoch or an IST offset. | Matches ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$ |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Error codes
| Code | Status | Meaning | Retrying |
|---|---|---|---|
API_VERSION_UNSUPPORTED | 400 | That API version is no longer supported. | Do not retry automatically |
IDEMPOTENCY_KEY_INVALID | 400 | That Idempotency-Key does not meet the required format. | Do not retry automatically |
IDEMPOTENCY_KEY_REQUIRED | 400 | An Idempotency-Key header is required for this request. | Do not retry automatically |
REQUEST_MALFORMED | 400 | The request could not be parsed. | Do not retry automatically |
AUTH_KEY_EXPIRED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_INVALID | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_MISSING | 401 | No API key was presented. | Do not retry automatically |
AUTH_KEY_REVOKED | 401 | The API key is not valid. | Do not retry automatically |
INSUFFICIENT_BALANCE | 402 | The available balance is not enough for this request. | Do not retry automatically |
AUTH_IP_NOT_ALLOWED | 403 | This API key may not be used from this address. | Do not retry automatically |
ENTITLEMENT_MISSING | 403 | This organization is not entitled to that product in this environment. | Do not retry automatically |
ORGANIZATION_SUSPENDED | 403 | This organization is not active. | Do not retry automatically |
PRODUCT_NOT_AVAILABLE | 403 | That product is not available. | Do not retry automatically |
PRODUCT_RETIRED | 403 | That product has been withdrawn. | Do not retry automatically |
SCOPE_INSUFFICIENT | 403 | This API key does not carry the scope this product requires. | Do not retry automatically |
PRODUCT_NOT_FOUND | 404 | No such product. | Do not retry automatically |
IDEMPOTENCY_KEY_REUSED | 409 | That idempotency key was already used for a different request. | Do not retry automatically |
PRICE_UNAVAILABLE | 409 | No active price covers this product right now. | Safe to retry |
REQUEST_IN_PROGRESS | 409 | An earlier attempt with this key is still running. | Safe to retry |
SETTLEMENT_PENDING | 409 | This request is awaiting reconciliation by an operator. | Do not retry automatically |
API_VERSION_SUNSET | 410 | That API version passed its announced sunset date. | Do not retry automatically |
REQUEST_TOO_LARGE | 413 | The request body is too large. | Do not retry automatically |
UNSUPPORTED_MEDIA_TYPE | 415 | That content type is not accepted on this route. | Do not retry automatically |
SANDBOX_FIXTURE_MISSING | 422 | No sandbox fixture exists for this input. Use a different test value. | Do not retry automatically |
UPSTREAM_REJECTED | 422 | The upstream source rejected the input. | Do not retry automatically |
VALIDATION_FAILED | 422 | The request payload is invalid. | Do not retry automatically |
CONCURRENCY_LIMIT | 429 | Too many simultaneous requests. | Safe to retry |
QUOTA_EXCEEDED | 429 | The allowance for this window is spent. | Do not retry automatically |
RATE_LIMITED | 429 | Too many requests. | Safe to retry |
INTERNAL_ERROR | 500 | An unexpected error occurred. | Safe to retry |
OUTCOME_UNCERTAIN | 502 | The outcome of this request is not yet known. Retry with the same Idempotency-Key. | Do not retry automatically |
UPSTREAM_UNAVAILABLE | 502 | The upstream source is unavailable. Retry shortly. | Safe to retry |
MAINTENANCE_MODE | 503 | The service is in a maintenance window. | Safe to retry |
NO_PROVIDER_AVAILABLE | 503 | No provider can serve this product right now. | Safe to retry |
SERVICE_OVERLOADED | 503 | The service is shedding load. Retry shortly. | Safe to retry |
UPSTREAM_TIMEOUT | 504 | The upstream source did not respond in time. | Safe to retry |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Rate limits
| Scope | Limit | Window | At the limit |
|---|---|---|---|
| Your API key, within your organisation's limit | The figure in X-RateLimit-Limit | Per minute | 429 RATE_LIMITED, with Retry-After in seconds. Every answer past authentication carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Use cases
- Lending and NBFC - GSTIN and status check before MSME credit assessment
- Fintech and payments - merchant registration check at onboarding
- Marketplaces - seller GST registration check before a catalog goes live
- Procurement - supplier GSTIN and filing check before invoice release
- Logistics and freight - consignor and consignee registration check
- Insurance - network partner and intermediary registration check
What this service does
Fields a GSTIN check can return
You can get the registration status, legal and trade name, taxpayer type and constitution, registration date, state jurisdiction and principal place of business. The Advanced depth adds filing and return-status information. Which fields are actually present varies by data source and by the individual registration record.
Basic profile or Advanced filing history
Basic covers the registration profile, and Advanced adds the filing and return-status information held for the registration. That helps when a decision rests on ongoing compliance behavior. Your service contract decides which depth you can call.
A check inside your signup or vendor flow
Connect the check to a signup form, vendor master, procurement system, loan origination system or accounts payable queue. The registration is then confirmed as part of the transaction, with no separate manual lookup.
Re-check registrations after onboarding
A registration status can change once a counterparty is live. The same check covers a one-time review at signup and a scheduled sweep across your existing merchant, vendor or borrower base.
How a check runs
Agree the GST checks you need
Tell us which checks you want and which depth your workflow needs. Use Get API to start the conversation and agree the service contract.
Connect the check to your systems
Add the verification step to your onboarding form, vendor master, procurement system or review dashboard. The technical documentation you get at onboarding shows how.
Send the GSTIN
Your application sends the GSTIN exactly as the counterparty gave it, and we process the request at the depth you agreed.
Read the registration details
The registration information available for that number comes back in a structured response. Which fields appear depends on the data source and on the individual record.
Act on the GST result
Use the response for the onboarding, procurement, payment or credit decision you collected it for, and store what came back for later review.
Questions
- What do I send to check a GSTIN?
- Just the GSTIN, exactly as the counterparty gave it to you. You do not need to upload a document or an image for this check.
- What details come back from a GST verification?
- The registration information available for that number: status, legal and trade name, taxpayer type and constitution, registration date, jurisdiction and principal place of business. At the Advanced depth you also get the filing and return-status information recorded. The fields you receive vary by data source and by the individual record.
- What is the difference between the Basic and Advanced GST checks?
- Basic covers the registration profile. Advanced adds the filing and return-status information held for the registration, which supports decisions that depend on how regularly a counterparty files. This page covers both, and your service contract decides which depth you can call.
- Do I need consent to verify a GSTIN?
- GST registration data describes a business, not an individual. Even so, run the check only for a genuine business purpose, such as an onboarding, procurement, payment or credit decision. Handle what comes back under your existing counterparty data rules.
- How do I get access to the GST Verification API?
- Use Get API and tell us about your workflow and volumes. We agree access, the supported depths and the integration documentation as part of the service contract.
- Why do GST results differ from one registration to another?
- Registrations differ in what has been recorded against them, and data sources differ in what they can return. A trade name, an extra place of business or filing information may be present for one registration and missing for another.
Catalog entry last updated .