Three moments, three different tools
| When | What it solves | What to use |
|---|---|---|
| A vendor is created | A typo or a cancelled registration enters the master on day one | One lookup, called from your server, before the record is saved |
| You clean the existing master | Years of unverified vendors | Bulk upload from the dashboard, or the API in a throttled loop |
| Every day after that | A registration is cancelled or a vendor stops filing after you onboarded them | A watchlist with a signed webhook |
At vendor creation: what to check and what to store
Uppercase the GSTIN and check its format locally first, so a typo never costs a request. A malformed GSTIN is rejected with HTTP 400 and is not charged.
Then call GET /v1/gstin/{gstin} from your server with the key in an x-api-key header. Never put the key in browser code. Store the legal name, the status, the taxpayer type and the state, with the date and time you checked: the result is true as of that moment, not forever.
Decide the policy before you build it: whether a Cancelled registration blocks the vendor or only raises a warning for a person to review.
Re-verifying the vendors you already have
Through the API at the default 60 requests a minute, 10,000 vendors take about 2 hours 47 minutes. Run it as an overnight job and handle HTTP 429 by waiting and retrying rather than failing the batch.
For a one-off clean-up, bulk upload is simpler once you have bought a credit pack: an Excel sheet of up to 2,000 rows goes in and comes back filled in, and rows that fail are not charged. Ten thousand vendors is five files.
After that: a webhook instead of a nightly poll
Put the vendors on a watchlist that re-checks daily, weekly or monthly. When something changes, your endpoint receives an HMAC-signed POST, typically within the hour. Register the endpoint with POST /v1/webhooks: it must be HTTPS and publicly reachable, and an account can have up to 3 endpoints. Use the secret to verify each delivery, and fire a test event before real data flows.
Monitoring is a separate subscription and is billed apart from your credit balance, so it does not draw down the credits you use for lookups.
What to do with each response
| Status | Meaning | What your code should do |
|---|---|---|
| 200 | Found | Store the result with the check date |
| 400 | Malformed GSTIN | Reject the input; not charged; do not retry |
| 401 | Missing or invalid key | Stop and alert; do not retry |
| 402 | Out of credits | Stop the batch and alert someone; do not retry |
| 404 | GSTIN not registered | Flag the vendor for review; this is an answer, not an error, and it is not charged |
| 429 | Rate limit exceeded | Wait and retry with backoff, at most 3 attempts |
| 502 | Provider temporarily unavailable | Safe to retry with backoff, at most 3 attempts |
A small client that retries only what it should
This Node.js example retries 429 and 502 with a growing wait and treats everything else as final:
const BASE = 'https://www.gstinapi.in';
const sleep = ms => new Promise(r => setTimeout(r, ms));
async function verify(gstin, attempts = 3) {
for (let i = 0; i < attempts; i++) {
const res = await fetch(BASE + '/v1/gstin/' + gstin, {
headers: { 'x-api-key': process.env.GSTINAPI_KEY },
});
if (res.ok) return (await res.json()).data;
if (res.status === 404) return null; // not registered
if (res.status === 402) throw new Error('Out of credits');
if (![429, 502].includes(res.status)) throw new Error('Lookup failed: ' + res.status);
await sleep(2 ** i * 1000); // 1s, 2s, 4s
}
throw new Error('Gave up after retries');
}
// Re-checking a list: stay under 60 requests a minute.
async function recheck(gstins) {
for (const g of gstins) {
const data = await verify(g);
// save data and new Date() against the vendor here
await sleep(1100);
}
}Keep the key in an environment variable and run this from your server. Add "?include=profile" to the lookup if you also want the constitution of business and jurisdiction fields.
Frequently asked questions
How many GSTINs can I verify per hour through the API?
At the default limit of 60 requests a minute per key, 3,600 an hour. Higher limits are negotiated on volume plans.
Should I store the result in my ERP?
Yes, with the date you checked it, and treat it as true as of that date. Before a payment or an input tax credit decision, check again: a cancellation from this morning only shows in a live lookup.
What should the ERP do with a Cancelled vendor?
That is a business decision to make in advance: block the vendor, or warn and let a person decide. The API returns the status; it does not decide for you.
Does a webhook replace the check at creation?
No. The webhook tells you about changes after a vendor is on a watchlist. The check at creation is what stops a bad record from entering the master.
Is there a fee for failed lookups?
No. Failed calls are not charged. Monitoring is a separate subscription.
More from the blog
Try it on a real GSTIN
Up to 75 free lookups: 10 on signup and 65 more across three setup steps. No card, and they never expire.
Create a free account