API documentation

This is a GST verification API with x-api-key authentication: every request must include your API key in the x-api-key header. Generate and rotate keys from your dashboard at any time — there is no separate approval step.

                x-api-key: YOUR_API_KEY
            

For a single GSTIN, send a GET request with the GSTIN as a path parameter. Each successful verification consumes one credit from your account.

                GET https://gstinapi.com/api/get-taxpayer-info/{gstin}
            

For a list — a vendor master, a customer file, an onboarding queue — use the bulk endpoints below instead of looping this one yourself.

Every endpoint on this page is also described by a machine-readable OpenAPI 3.1 document (YAML), generated from the same configuration the API enforces — import it into Postman, Insomnia or a client generator instead of writing request code by hand.

Code examples

There is no separate GST verification API SDK to install — the plain REST endpoint works directly from any HTTP client. Copy-paste examples for the most common stacks below, including a working call you can drop straight into a Laravel HTTP client, a Node.js service, or a Python script.

async function verifyGSTIN(gstin) {
  const response = await fetch(
    `https://gstinapi.com/api/get-taxpayer-info/${gstin}`,
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );

  return response.json();
}

const result = await verifyGSTIN('27AAACR5055K1Z7');
console.log(result.taxpayer_data.name, result.taxpayer_data.status);

function verifyGSTIN(string $gstin): array
{
    $curl = curl_init("https://gstinapi.com/api/get-taxpayer-info/{$gstin}");

    curl_setopt_array($curl, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['x-api-key: YOUR_API_KEY'],
    ]);

    $response = curl_exec($curl);
    curl_close($curl);

    return json_decode($response, true);
}

$result = verifyGSTIN('27AAACR5055K1Z7');
echo $result['taxpayer_data']['name'];

import requests

def verify_gstin(gstin: str) -> dict:
    url = f"https://gstinapi.com/api/get-taxpayer-info/{gstin}"
    headers = {"x-api-key": "YOUR_API_KEY"}

    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

result = verify_gstin("27AAACR5055K1Z7")
print(result["taxpayer_data"]["name"], result["taxpayer_data"]["status"])

Want a full walkthrough instead of a snippet? See integrating in Laravel or integrating in Node.js.

Bulk GSTIN verification runs as a job, not as a long request. Submit up to 10,000 GSTINs, get a job ID back immediately, then poll it while our queue works through the list at a pace we control. That pacing is the point: your list is verified as fast as is safe for the government data source, and you never hold a connection open for an hour or have to build your own rate limiting.

1. Submit the list

Send an array of GSTINs, or paste a blob as text and we will pull the GSTINs out of it. Duplicates are verified once and charged once.

POST https://gstinapi.com/api/bulk/jobs
x-api-key: YOUR_API_KEY
Content-Type: application/json

{ "name": "Vendor master", "gstins": ["27AAACR5055K1Z7", "29AAACI1195H1ZI"] }

202 Accepted
{ "success": true, "job": { "job_id": "9f1c…", "status": "queued", "progress": { "total_rows": 2, "total_lookups": 2, "completed_lookups": 0 } } }

2. Poll the job

Poll every few seconds until status is completed, cancelled or failed. A completed job carrying stopped_reason: insufficient_credits ran out of balance part way through — the rows it never checked were never charged.

GET https://gstinapi.com/api/bulk/jobs/{job_id}

3. Collect the results

One entry per submitted row, in the order you sent them, paginated. Add ?format=csv for a spreadsheet, or ?outcome=ok to take only the rows that resolved. Results can be read while the job is still running.

GET https://gstinapi.com/api/bulk/jobs/{job_id}/results
GET https://gstinapi.com/api/bulk/jobs/{job_id}/results?format=csv
DELETE https://gstinapi.com/api/bulk/jobs/{job_id}     # cancel a running job

Prefer not to write any code? Upload a spreadsheet in your dashboard and download it back with the registration details filled in, every original column intact. Background and worked throughput numbers are in the bulk GSTIN verification guide.

Response fields

Every GST API JSON response example below comes from the same schema: taxpayer registration details, GSTR filing history, and e-invoicing/e-way bill status as nested JSON. The most commonly used fields:

Client libraries

You do not have to build the request by hand. Two official, MIT-licensed, zero-dependency clients wrap the endpoint above, and both add an offline layer the REST API has no way to offer: format and check digit validation that costs nothing and needs no key, so a mistyped number never becomes a request.

npm install @dlminds/gstin-api

pip install gstin-toolkit

Prefer to generate a client instead? The OpenAPI 3.1 document describes every endpoint on this page, and the client libraries page compares the two hand-written ones side by side.

Rate limits and credits

Requests are rate-limited per API key to keep the service fast and reliable for every account. Each verification consumes one credit, and only a lookup that actually returns a registration is charged — a mistyped number, a GSTIN with no registration behind it, and an outage on our side all cost nothing. Bulk jobs are the exception to rate limiting rather than a victim of it: submit as large a list as you like and the queue paces the work for you, so there is no throttle for your client to back off from. A bulk job that exhausts your balance stops there and says so instead of failing row by row.

When a call fails and you need to know whether the problem is yours, ours or the government upstream's, the status page answers it — live component health plus the availability we have measured, with a JSON version to poll from your own monitoring. What we commit to, how downtime is counted and what you can claim when we miss it is in the service level agreement.