How to verify a GST number in PHP

1. The call, with cURL

There is no PHP SDK, and you do not need one — the API is a single GET request with one header.

<?php
$gstin = "33AAACC1206D1ZN";

$ch = curl_init("https://gstinapi.in/v1/gstin/" . urlencode($gstin));
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ["x-api-key: gak_your_key_here"],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Lookup failed with HTTP $status");
}

$data = json_decode($body, true);
echo $data["legal_name"], " — ", $data["status"];

2. Validate the GSTIN offline first

A malformed GSTIN returns 400 and is not charged, but the round trip is wasted. The check digit is computable in PHP, so reject typos before the request goes out.

<?php
function is_valid_gstin(string $gstin): bool
{
    $codes = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
    $gstin = strtoupper(trim($gstin));

    if (strlen($gstin) !== 15) {
        return false;
    }

    $total = 0;
    for ($i = 0; $i < 14; $i++) {
        $index = strpos($codes, $gstin[$i]);
        if ($index === false) {
            return false;
        }
        $product = $index * ($i % 2 ? 2 : 1);
        $total += intdiv($product, 36) + ($product % 36);
    }

    $expected = $codes[(36 - $total % 36) % 36];
    return $gstin[14] === $expected;
}

var_dump(is_valid_gstin("33AAACC1206D1ZN")); // true
var_dump(is_valid_gstin("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

<?php
function verify_gstin(string $gstin, string $apiKey, int $attempts = 3): ?array
{
    $retryable = [429, 502];

    for ($attempt = 0; $attempt < $attempts; $attempt++) {
        $ch = curl_init("https://gstinapi.in/v1/gstin/" . urlencode($gstin));
        curl_setopt_array($ch, [
            CURLOPT_HTTPHEADER     => ["x-api-key: $apiKey"],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 10,
        ]);
        $body   = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($status === 200)  return json_decode($body, true);
        if ($status === 404)  return null;   // valid format, not registered
        if ($status === 402)  throw new RuntimeException("Out of credits");

        if (!in_array($status, $retryable, true)) {
            $error = json_decode($body, true)["error"] ?? "HTTP $status";
            throw new RuntimeException($error);
        }

        if ($attempt < $attempts - 1) {
            sleep(2 ** $attempt);   // 1s, then 2s
        }
    }

    throw new RuntimeException("GST provider unavailable after retries");
}

4. Wiring it into Laravel

Put the key in .env and read it through config(), never inline in a controller. Laravel ships an HTTP client that handles retries for you, so the hand-rolled loop above collapses to a couple of lines.

<?php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['x-api-key' => config('services.gstin.key')])
    ->timeout(10)
    ->retry(3, 1000, fn ($e, $r) => in_array($r?->status(), [429, 502], true))
    ->get("https://gstinapi.in/v1/gstin/{$gstin}");

if ($response->status() === 404) {
    return null;
}

return $response->throw()->json();

Frequently asked questions

The same guide in another language