GSTIN Profile API
New
Read a GSTIN's full registration profile, from filings and signatories to turnover band and places of business, before you onboard, lend to or pay a business.
Overview
A GST registration says more about a business than whether it exists. The registry also holds its return filings, its authorised signatories, its turnover band, its places of business and its compliance rating. Lenders, marketplaces and procurement teams use that wider record to judge a counterparty, not just to confirm a number. Collecting it by hand means a portal search per business and a screenshot for the file. Your application sends a GSTIN, and optionally a financial year, and gets back the registration profile as structured data. Which fields come back depends on the data source, the registration and the service contract you select.
- Category
- Tax & Compliance Services
- Coverage
- GST registrations across Indian states and union territories
- Input
- GSTIN, plus a financial year for that year's filings
- Output
- Registration profile: status, dates, places of business, signatories, filings, turnover band and compliance details
- Typical users
- Lenders and NBFCs, B2B marketplaces, payment platforms, procurement and vendor onboarding teams
- Coverage note
- Registrations across Indian states and union territories. Available fields vary by data source and registration.
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 |
input. | string | Optional | — | Matches ^20[0-9]{2}-[0-9]{2}$ |
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-advance \
-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-advance", {
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-advance",
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. | boolean or null | Always | Whether e-invoicing is mandatory for the taxpayer. | — |
data. | string or any or null | Always | — | — |
data. | object or any or null | Always | How to reach the taxpayer. Returned live and never stored. | — |
data. | array of objects | Always | Every authorised signatory the registration names, each once; empty when it names none. | — |
data. | string or null | Always | — | — |
data. | array of objects | Always | The returns the registry lists, flattened from its per-year groups, in its order; empty when it lists none. | — |
data. | string or any or null | Always | The financial year, 2023-24. | — |
data. | string or null | Always | The tax period as the registry names it (for example February). | — |
data. | string or null | Always | The return's form (for example GSTR1, GSTR3B), upper-cased, as given. | — |
data. | string or null | Always | The return's status word (for example FILED), upper-cased, as given. | — |
data. | string or any or null | Always | The day it was filed. | — |
data. | string or null | Always | The acknowledgement the filing was given, as given. | — |
data. | string or null | Always | How the return was filed (for example ONLINE), upper-cased, as given (Release 1.1). | — |
data. | object or any or null | Always | The turnover and income bands; null when the registry publishes neither. | — |
data. | array of objects | Always | The services the registration lists, each once; empty when it lists none. | — |
data. | string or null | Always | — | — |
data. | string or null | Always | The Services Accounting Code, as given. | — |
data. | string or null | Always | The registry's compliance rating, as given. | — |
data. | string or null | Always | What the registry records as the core of the business, as given. | — |
data. | boolean or null | Always | Whether the registry records a visit to the premises. | — |
data. | boolean or null | Always | Whether the taxpayer's Aadhaar is recorded as verified. | — |
data. | boolean or null | Always | Whether the taxpayer's eKYC is recorded as verified. | — |
data. | array of objects | Always | The goods the registration lists, each once; empty when it lists none (Release 1.1). | — |
data. | string or null | Always | — | — |
data. | string or null | Always | The Harmonised System of Nomenclature code, as given. | — |
data. | string or null | Always | The registry's CAN flag for the taxpayer, as given; its vocabulary is undocumented (Release 1.1). | — |
data. | boolean or null | Always | Whether the registry holds compliance details for the taxpayer (Release 1.1). | — |
data. | string or any or null | Always | When the taxpayer's Aadhaar was validated (Release 1.1). | — |
data. | number or null | Always | The share of tax paid in cash, as a number from 0 to 100 (the source writes it as text); null when not given (Release 1.1). | Minimum 0. Maximum 100 |
data. | string or null | Always | The financial year that share is for, as given (Release 1.1). | — |
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
- Business lending: reading filing history and turnover band before underwriting
- Marketplaces: checking a seller files returns before payouts start
- Procurement: confirming authorised signatories before a contract
- Payment platforms: reading e-invoicing status before enabling invoicing
- Counterparty review: re-reading a registration on a cycle for status changes
What this service does
The full registration profile
Legal and trade name, status, dates, constitution, taxpayer type, places of business, jurisdictions, e-invoicing status, signatories, filings, turnover band and compliance rating, where the registry holds them.
Filings for the year you choose
Send a financial year with the GSTIN to read the returns filed for that year, each with its form, period, status and filing date.
One identifier in, a structured profile out
You send the GSTIN the business gave you. There is no document to upload and no portal to search.
Built for decisions, not just validation
Use GST Verification to confirm a number. Use GSTIN Profile when the decision depends on how the business files, trades and is run.
How a check runs
Arrange access
Tell us where the GSTIN profile fits in your onboarding or credit process. We arrange access for your organization under the applicable service contract.
Send the GSTIN
Your application sends the GSTIN, and a financial year if you need that year's filings.
The profile is retrieved
The service reads the registration profile the GST registry holds for that number.
Read the structured profile
Your application receives the registration details, filings, signatories and turnover band available for the registration.
Decide and record
Route the result into the onboarding, credit or payment decision it was requested for, and store it with that decision.
Questions
- What do I send to read a GSTIN profile?
- The GSTIN, exactly as the business gave it to you. You can add a financial year to read the returns filed in that year.
- How is GSTIN Profile different from GST Verification?
- GST Verification confirms a GSTIN and reads its basic registration details. GSTIN Profile reads the wider record: return filings, authorised signatories, turnover band, places of business, compliance rating and more, where the registry holds them.
- Does the profile include return filings?
- Yes, where the registry lists them: each return with its form, period, status, filing date and acknowledgement number. Send a financial year to choose which year is read.
- Why are some fields empty?
- The registry does not hold every field for every registration, and what is returned depends on the data source and your service contract. Treat an empty field as unknown rather than as a finding.
- Do I need consent to read a GSTIN profile?
- A GST registration is a business record. The profile can still include signatories' names and the business's contact details, so read it for a stated business purpose and limit who sees the result.
- How do I get access to the GSTIN Profile API?
- Start with Get API and tell us how the profile fits your onboarding or credit process, and what volumes you expect. We set up access under the applicable service contract.
Catalog entry last updated .