How to Verify a GST Number Using an API (Step-by-Step)

To verify a GST number using an API, send an authenticated GET request with the GSTIN in the URL and read the taxpayer status back from the JSON response — no browser, no captcha, no manual copy-paste. This guide walks through every step end to end, from getting a key to handling a cancelled status in production.

Verifying a GST number by hand means opening the GST portal, typing in the GSTIN, solving a captcha, and reading the result off the screen — fine for one lookup, unworkable if you need to check a GSTIN every time a vendor signs up or an invoice gets raised. A GST verification API does the same lookup programmatically, in under a second, as part of your own application flow. Here is exactly how.

What you need before you start

• An API key — sign up free and verify your email to get one along with 20 free credits.
• The GSTIN you want to verify (a 15-character alphanumeric code, e.g. 27AAACR5055K1Z7).
• Any HTTP client — curl, your browser, or a few lines of code in your app.

If you only need to check a number once and would rather not write any code at all, the free GST number search tool runs the identical live lookup with no signup, up to five times a day. Everything below is for when the check needs to happen inside your own application.

Step 1: Get your API key

Every request must be authenticated. After signing up and verifying your email, generate an API key from your dashboard. Keep it out of client-side code and version control — treat it like a password, and store it in an environment variable rather than a config file that gets committed.

Step 2: Call the verification endpoint

Send a GET request to the endpoint below, replacing {gstin} with the number you want to verify and passing your key in the X-API-Key header:

 curl -s https://gstinapi.com/api/get-taxpayer-info/27AAACR5055K1Z7 \
  -H "X-API-Key: YOUR_API_KEY" 

That is the entire authenticated surface — there is no session, no consent flow, and no separate token exchange, because the endpoint is reading a public registration record rather than acting on the taxpayer's behalf. The same shape works from any language; see the guides for Laravel, Node.js, Python, and Go if you are wiring this into an existing codebase rather than testing from a terminal.

Step 3: Read the response

A successful call returns a JSON object. The fields you will use most often:

• taxpayer_data.status — Active, Cancelled, or Suspended.
• taxpayer_data.legal_name and taxpayer_data.trade_name — legal name and trade name.
• taxpayer_data.pradr — the registered principal place of business.
• filing_data — recent GSTR filing history, useful for checking whether a business is actually compliant, not just registered.

These fields are not padding. A verified response for Reliance Industries Limited (27AAACR5055K1Z7, Maharashtra, Active) carries 354 filing records and 244 additional places of business — if you are parsing the payload into your own schema, plan for arrays that size, not the two-row example most quickstarts show. See the full API documentation for the complete response schema and code examples in JavaScript, PHP, and Python.

Step 4: Handle the edge cases

A production integration should account for a few things a one-off lookup doesn't need to:

• Invalid GSTIN format. Validate the 15-character structure client-side before making the call, to avoid burning a credit on an obviously malformed input.
• Cancelled or suspended status. Decide up front how your application should react — block the action, flag it for review, or just log it.
• Rate limits and credit balance. Requests fail once your credit balance hits zero, so surface that state clearly rather than letting it fail silently.

Where this fits in a real workflow

Most teams call this endpoint at one of three moments: when a vendor or customer is onboarded, right before an invoice is generated, or as part of a periodic compliance sweep across an existing vendor list. Whichever moment you pick, this is the same flow every time you need to verify a GST number using the API — one authenticated request, one JSON response. If you need to do the last one at scale, see our guide on bulk GSTIN verification. If you are onboarding vendors specifically, GST verification for vendor onboarding covers where in that flow the check typically sits.

API verification vs the government portal

Nothing about the underlying data changes when you switch from the portal to an API — you are reading the same public registration record either way. What changes is who does the work: a person clicking through a captcha one number at a time, or your own code making a call it can repeat automatically for every vendor, every invoice, every day. For a fuller side-by-side, including cost and audit-trail differences, see API verification versus manual verification. When you are ready, the GST API product page and pricing cover the full feature set and per-lookup cost.

Frequently asked questions