How to verify a GST number in Node.js

1. Install the Node.js library

An official client library exists for Node.js, and it handles the auth header and response parsing for you.

npm install gstinapi

Then verify a GSTIN in three lines:

import { GstinApi } from 'gstinapi';

const client = new GstinApi({ apiKey: 'gak_your_key_here' });

const result = await client.verify('33AAACC1206D1ZN');

console.log(result.legal_name);    // "CHENNAI CORPORATION LIMITED"
console.log(result.status);        // "Active"
console.log(result.taxpayer_type); // "Regular"

Source on GitHub · package registry

Without the package (native fetch)

The API is a single GET with one header, so you can skip the library entirely if you would rather not add a dependency.

const response = await fetch(
  'https://gstinapi.in/v1/gstin/33AAACC1206D1ZN',
  { headers: { 'x-api-key': 'gak_your_key_here' } }
);

if (!response.ok) throw new Error(`HTTP ${response.status}`);

const data = await response.json();
console.log(data.legal_name, data.status);

2. Validate the GSTIN offline first

A malformed GSTIN returns 400 and is never charged — but you still paid for the round trip. The check digit is computable locally, so reject typos before they leave your server.

const CODES = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';

export function isValidGstin(gstin) {
  const value = (gstin ?? '').trim().toUpperCase();
  if (value.length !== 15) return false;

  let total = 0;
  for (let i = 0; i < 14; i++) {
    const index = CODES.indexOf(value[i]);
    if (index === -1) return false;
    const product = index * (i % 2 ? 2 : 1);
    total += Math.floor(product / 36) + (product % 36);
  }

  const expected = CODES[(36 - (total % 36)) % 36];
  return value[14] === expected;
}

isValidGstin('33AAACC1206D1ZN'); // true
isValidGstin('33AAACC1206D1ZZ'); // false

This proves the GSTIN is well-formed. It cannot tell you whether the registration exists or is still active — only a live lookup does that, because registrations get cancelled.

3. Handle every status code

const RETRYABLE = new Set([429, 502]);
const sleep = ms => new Promise(r => setTimeout(r, ms));

export async function verify(gstin, apiKey, attempts = 3) {
  for (let attempt = 0; attempt < attempts; attempt++) {
    const res = await fetch(`https://gstinapi.in/v1/gstin/${gstin}`, {
      headers: { 'x-api-key': apiKey },
    });

    if (res.ok) return res.json();
    if (res.status === 404) return null;   // valid format, no such registration
    if (res.status === 402) throw new Error('Out of credits — recharge your account');

    if (!RETRYABLE.has(res.status)) {
      const { error } = await res.json().catch(() => ({}));
      throw new Error(error ?? `HTTP ${res.status}`);
    }

    if (attempt < attempts - 1) await sleep(2 ** attempt * 1000);
  }

  throw new Error('GST provider unavailable after retries');
}

4. Wiring it into Express or Next.js

Read the key from process.env and call the API server-side only — a key shipped to the browser is a key anyone can spend. In Next.js that means a route handler or server action, never a client component. Cache the result against the vendor record rather than re-verifying on every request.

// app/api/verify/route.js
import { GstinApi } from 'gstinapi';

const client = new GstinApi({ apiKey: process.env.GSTIN_API_KEY });

export async function POST(request) {
  const { gstin } = await request.json();
  const result = await client.verify(gstin);
  return Response.json(result);
}

Frequently asked questions

The same guide in another language