Skip to content

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.

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

POSThttps://gateway.staging.finsour.io/v1/business/gstin-advance

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

Scheme API key travels in the X-Api-Key header

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

Content type application/json

Headers

NameTypeRequiredDescriptionConstraints
Idempotency-KeystringRequiredA 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

NameTypeRequiredDescriptionConstraints
inputobjectRequiredThe details to check.—
input.gstinstringRequired—Matches ^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]Z[0-9A-Z]$. Exactly 15 characters
input.financialYearstringOptional—Matches ^20[0-9]{2}-[0-9]{2}$
optionsobjectOptionalSettings for this call.—
options.referencestringOptionalYour own reference for this call. It comes back unchanged as meta.reference.1 to 128 characters
options.consentobjectOptionalThe person's consent to this check.—
options.consent.obtainedbooleanRequiredSend true once the person has agreed to the check.Always true
options.consent.atstring (date-time)RequiredWhen the person gave consent.—
options.consent.purposestringRequiredWhat 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

Status 200 · content type application/json

NameTypePresentDescriptionConstraints
dataobjectAlwaysThe result of the check.—
data.foundbooleanAlways——
data.gstinstringAlways—Matches ^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]Z[0-9A-Z]$. Exactly 15 characters
data.legalNamestring or nullAlwaysThe taxpayer's legal name; for a proprietorship, the proprietor's own. Whole here; Finsour keeps only partial letters of it.—
data.tradeNamestring or nullAlwaysThe name the business trades under.—
data.statusstring or nullAlwaysThe registration's status word (for example ACTIVE, CANCELLED), upper-cased, as given.—
data.registeredOnstring or any or nullAlways——
data.cancelledOnstring or any or nullAlwaysThe day the registration was cancelled; null for one that has not been.—
data.constitutionstring or nullAlwaysThe constitution of the business (for example PRIVATE LIMITED COMPANY), upper-cased, as given.—
data.taxpayerTypestring or nullAlwaysThe taxpayer type (for example REGULAR), upper-cased, as given.—
data.natureOfBusinessarray of stringsAlwaysEvery nature of business the registration names, as given.—
data.principalPlaceobject or any or nullAlways——
data.additionalPlacesarray of objectsAlways——
data.additionalPlaces[].naturearray of stringsAlwaysWhat the place is used for, one entry each (for example Warehouse / Depot).—
data.additionalPlaces[].addressobject or any or nullAlways——
data.additionalPlaces[].fullAddressstring or nullAlwaysThe whole address on one line, as the registry prints it (Release 1.1).—
data.additionalPlaces[].latitudenumber or nullAlwaysThe place's latitude in decimal degrees, as the registry publishes it (Release 1.1).Minimum -90. Maximum 90
data.additionalPlaces[].longitudenumber or nullAlwaysThe place's longitude in decimal degrees (Release 1.1).Minimum -180. Maximum 180
data.additionalPlaces[].lastUpdatedOnstring or any or nullAlwaysWhen the registry last updated this place (Release 1.1).—
data.additionalPlaces[].contactobject or any or nullAlwaysThe place's own e-mail and mobile number, as the registry records them (Release 1.1). Returned live and never stored.—
data.centreJurisdictionobject or any or nullAlways——
data.stateJurisdictionobject or any or nullAlways——
data.eInvoicingEnabledboolean or nullAlwaysWhether the taxpayer is enabled for e-invoicing.—
data.eInvoicingMandatoryboolean or nullAlwaysWhether e-invoicing is mandatory for the taxpayer.—
data.lastUpdatedOnstring or any or nullAlways——
data.contactobject or any or nullAlwaysHow to reach the taxpayer. Returned live and never stored.—
data.authorizedSignatoriesarray of objectsAlwaysEvery authorised signatory the registration names, each once; empty when it names none.—
data.authorizedSignatories[].namestring or nullAlways——
data.filingsarray of objectsAlwaysThe returns the registry lists, flattened from its per-year groups, in its order; empty when it lists none.—
data.filings[].financialYearstring or any or nullAlwaysThe financial year, 2023-24.—
data.filings[].periodstring or nullAlwaysThe tax period as the registry names it (for example February).—
data.filings[].returnTypestring or nullAlwaysThe return's form (for example GSTR1, GSTR3B), upper-cased, as given.—
data.filings[].statusstring or nullAlwaysThe return's status word (for example FILED), upper-cased, as given.—
data.filings[].filedOnstring or any or nullAlwaysThe day it was filed.—
data.filings[].acknowledgementNumberstring or nullAlwaysThe acknowledgement the filing was given, as given.—
data.filings[].modestring or nullAlwaysHow the return was filed (for example ONLINE), upper-cased, as given (Release 1.1).—
data.turnoverobject or any or nullAlwaysThe turnover and income bands; null when the registry publishes neither.—
data.servicesarray of objectsAlwaysThe services the registration lists, each once; empty when it lists none.—
data.services[].descriptionstring or nullAlways——
data.services[].sacCodestring or nullAlwaysThe Services Accounting Code, as given.—
data.complianceRatingstring or nullAlwaysThe registry's compliance rating, as given.—
data.coreBusinessNaturestring or nullAlwaysWhat the registry records as the core of the business, as given.—
data.fieldVisitConductedboolean or nullAlwaysWhether the registry records a visit to the premises.—
data.aadhaarVerifiedboolean or nullAlwaysWhether the taxpayer's Aadhaar is recorded as verified.—
data.ekycVerifiedboolean or nullAlwaysWhether the taxpayer's eKYC is recorded as verified.—
data.goodsarray of objectsAlwaysThe goods the registration lists, each once; empty when it lists none (Release 1.1).—
data.goods[].descriptionstring or nullAlways——
data.goods[].hsnCodestring or nullAlwaysThe Harmonised System of Nomenclature code, as given.—
data.canFlagstring or nullAlwaysThe registry's CAN flag for the taxpayer, as given; its vocabulary is undocumented (Release 1.1).—
data.complianceDetailsAvailableboolean or nullAlwaysWhether the registry holds compliance details for the taxpayer (Release 1.1).—
data.aadhaarValidatedOnstring or any or nullAlwaysWhen the taxpayer's Aadhaar was validated (Release 1.1).—
data.cashTaxPaymentPercentnumber or nullAlwaysThe 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.cashTaxPaymentYearstring or nullAlwaysThe financial year that share is for, as given (Release 1.1).—
data.sourceobjectAlways——
data.source.fetchedAtstringAlwaysWhen 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

CodeStatusMeaningRetrying
API_VERSION_UNSUPPORTED400That API version is no longer supported.Do not retry automatically
IDEMPOTENCY_KEY_INVALID400That Idempotency-Key does not meet the required format.Do not retry automatically
IDEMPOTENCY_KEY_REQUIRED400An Idempotency-Key header is required for this request.Do not retry automatically
REQUEST_MALFORMED400The request could not be parsed.Do not retry automatically
AUTH_KEY_EXPIRED401The API key is not valid.Do not retry automatically
AUTH_KEY_INVALID401The API key is not valid.Do not retry automatically
AUTH_KEY_MISSING401No API key was presented.Do not retry automatically
AUTH_KEY_REVOKED401The API key is not valid.Do not retry automatically
INSUFFICIENT_BALANCE402The available balance is not enough for this request.Do not retry automatically
AUTH_IP_NOT_ALLOWED403This API key may not be used from this address.Do not retry automatically
ENTITLEMENT_MISSING403This organization is not entitled to that product in this environment.Do not retry automatically
ORGANIZATION_SUSPENDED403This organization is not active.Do not retry automatically
PRODUCT_NOT_AVAILABLE403That product is not available.Do not retry automatically
PRODUCT_RETIRED403That product has been withdrawn.Do not retry automatically
SCOPE_INSUFFICIENT403This API key does not carry the scope this product requires.Do not retry automatically
PRODUCT_NOT_FOUND404No such product.Do not retry automatically
IDEMPOTENCY_KEY_REUSED409That idempotency key was already used for a different request.Do not retry automatically
PRICE_UNAVAILABLE409No active price covers this product right now.Safe to retry
REQUEST_IN_PROGRESS409An earlier attempt with this key is still running.Safe to retry
SETTLEMENT_PENDING409This request is awaiting reconciliation by an operator.Do not retry automatically
API_VERSION_SUNSET410That API version passed its announced sunset date.Do not retry automatically
REQUEST_TOO_LARGE413The request body is too large.Do not retry automatically
UNSUPPORTED_MEDIA_TYPE415That content type is not accepted on this route.Do not retry automatically
SANDBOX_FIXTURE_MISSING422No sandbox fixture exists for this input. Use a different test value.Do not retry automatically
UPSTREAM_REJECTED422The upstream source rejected the input.Do not retry automatically
VALIDATION_FAILED422The request payload is invalid.Do not retry automatically
CONCURRENCY_LIMIT429Too many simultaneous requests.Safe to retry
QUOTA_EXCEEDED429The allowance for this window is spent.Do not retry automatically
RATE_LIMITED429Too many requests.Safe to retry
INTERNAL_ERROR500An unexpected error occurred.Safe to retry
OUTCOME_UNCERTAIN502The outcome of this request is not yet known. Retry with the same Idempotency-Key.Do not retry automatically
UPSTREAM_UNAVAILABLE502The upstream source is unavailable. Retry shortly.Safe to retry
MAINTENANCE_MODE503The service is in a maintenance window.Safe to retry
NO_PROVIDER_AVAILABLE503No provider can serve this product right now.Safe to retry
SERVICE_OVERLOADED503The service is shedding load. Retry shortly.Safe to retry
UPSTREAM_TIMEOUT504The 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

ScopeLimitWindowAt the limit
Your API key, within your organisation's limitThe figure in X-RateLimit-LimitPer minute429 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

  1. 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.

  2. Send the GSTIN

    Your application sends the GSTIN, and a financial year if you need that year's filings.

  3. The profile is retrieved

    The service reads the registration profile the GST registry holds for that number.

  4. Read the structured profile

    Your application receives the registration details, filings, signatories and turnover band available for the registration.

  5. 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 .