Bulk GSTIN Verification: Verify Hundreds of GSTINs at Once

This is a practical guide to bulk GSTIN verification: you have a vendor master with a few hundred GSTINs, or a customer list you inherited from a spreadsheet, and you need every one of them checked. There are two ways to do it — a queued batch job, or a controlled loop over the single-lookup endpoint. This article covers the loop, and when to reach for it. Either way, here is how to run batch GST verification without hitting rate limits, wasting credits, or writing something that falls over halfway through a 5,000-row file.

Two ways to do this, and when each one is right

There is now a dedicated batch endpoint: POST /api/bulk/jobs takes up to 10,000 GSTINs, queues them, and hands back a job you poll. It does the deduplication, pacing, offline pre-validation and resumption described below on the server, and it only charges for rows that resolve to a live registration. If you are verifying a vendor master or any list you did not hand-write, use the batch endpoint — that guide costs a realistic 5,000-row file line by line.

The rest of this article is the other approach: calling the single real-time GST verification API endpoint in a controlled loop. That is still the better tool for a couple of dozen numbers, for an ad-hoc script, or when you want each result the moment it lands rather than at the end of a job. What follows is how to do it without hitting rate limits or paying for the same number twice.

Step 1: Deduplicate and validate the format first

Before you spend a single credit, filter your list down to unique, correctly formatted GSTINs. A GSTIN is exactly 15 alphanumeric characters — anything else is a data-entry error, not something worth an API call.

const GSTIN_PATTERN = /^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$/;

const clean = [...new Set(rawGstins)].filter((g) => GSTIN_PATTERN.test(g));

Step 2: Batch requests with a concurrency limit

Firing 5,000 requests at once will hit your rate limit and likely get throttled. Process them in small concurrent batches instead — this Node.js example runs 10 at a time:

async function verifyBatch(gstins, batchSize = 10) {
  const results = [];

  for (let i = 0; i < gstins.length; i += batchSize) {
    const batch = gstins.slice(i, i + batchSize);
    const batchResults = await Promise.allSettled(batch.map(verifyGstin));
    results.push(...batchResults);

    // small delay between batches to stay well under the rate limit
    await new Promise((r) => setTimeout(r, 250));
  }

  return results;
}

Promise.allSettled matters here — it lets the batch finish even if a handful of GSTINs are invalid or the API returns an error for one of them, instead of one failure aborting the whole run.

Step 3: Run it as a background job, not a request

Anything beyond a couple dozen GSTINs should run outside the request/response cycle — a queued job in Laravel, a background worker in Node, or a scheduled task. Store progress so a large run can be resumed if it is interrupted, and surface a completion notification rather than making a user wait on a spinner.

Step 4: Watch your credit balance

A lookup that returns a live registration consumes one credit; a number that is not registered does not. In a loop you pay for each call you choose to make, so the deduplication in Step 1 is what keeps the bill down — the batch endpoint does that for you. Before kicking off a batch of 2,000 GSTINs, check your remaining balance — and remember that pricing drops from ₹0.50 to ₹0.40 per verification once a single purchase crosses 2,500 credits, which usually makes sense to buy ahead of a large one-off cleanup.

Step 5: Act on the status, not just the pass/fail

A bulk run’s point is usually to flag problems, not just confirm everything is fine. Segment results into at least three buckets: verified and active, verified but cancelled/suspended, and failed to verify (bad format, API error, or GSTIN not found) — each needs a different follow-up.

For the request/response shape used in every call above, see the API documentation. If you are running this for the first time, start with a batch of 20–30 GSTINs on your free credits to confirm the pipeline works end to end before pointing it at your full vendor list.