Connecting GST verification to your ERP: the vendor-master pattern

Three moments to verify a GSTIN, what to store, how long a re-check of 10,000 vendors takes, and a small client that retries the right errors.

By gstinapi.in team · Published 16 November 2026 · Last reviewed 16 November 2026

Three moments, three different tools

WhenWhat it solvesWhat to use
A vendor is createdA typo or a cancelled registration enters the master on day oneOne lookup, called from your server, before the record is saved
You clean the existing masterYears of unverified vendorsBulk upload from the dashboard, or the API in a throttled loop
Every day after thatA registration is cancelled or a vendor stops filing after you onboarded themA 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

StatusMeaningWhat your code should do
200FoundStore the result with the check date
400Malformed GSTINReject the input; not charged; do not retry
401Missing or invalid keyStop and alert; do not retry
402Out of creditsStop the batch and alert someone; do not retry
404GSTIN not registeredFlag the vendor for review; this is an answer, not an error, and it is not charged
429Rate limit exceededWait and retry with backoff, at most 3 attempts
502Provider temporarily unavailableSafe 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.

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