GST Taxpayer Search — API Docs

Zyada tar requests step 1 mein hi ho jaati hain (0.2–1.5s). Backend andar hi saari websites rotate karta hai; ek site down ho to agli try hoti hai. Error sirf tab aata hai jab sab fail ho jaayein.

Request

{ "gstin": "09ALIPB1014E2ZS" }

Response — success

{
  "success": true,
  "source": "busy",                 // kis website se data aaya
  "taxpayer": {
    "gstin": "09ALIPB1014E2ZS",
    "lgnm": "NAVEEN KUMAR BAJAJ",
    "tradeNam": "SHIV AGARBATTI BHANDAR",
    "sts": "Active",
    "rgdt": "28 Feb 2025",
    "ctb": "Proprietorship",
    "dty": "Regular",
    "pradr": { "addr": { "bno": "0309Q", "st": "KHUNIPUR", "loc": "Gorakhpur", "dst": "Gorakhpur", "stcd": "Uttar Pradesh", "pncd": "273001" } },
    "nba": ["Retail Business", "Wholesale Business"],
    "ctj": "State - CBIC,Zone - LUCKNOW,...",
    "stj": "State - Uttar Pradesh,Zone - Gorakhpur,...",
    "pan": "ALIPB1014E",              // full-info fields (admin me "Full info" ON ho to)
    "members": ["NAVEEN KUMAR BAJAJ"],
    "turnover": "Slab: Rs.25 Cr. to 100 Cr.",
    "hsn": [{ "code": "8013", "type": "HSN", "desc": "Cashew nuts" }],
    "returns": [{ "type": "GSTR1", "period": "082026", "filed_on": "2026-09-11", "status": "FILED", "delay_days": 0, "arn": "AA090826900113C" }]
  },
  "goods_service": null
}

Response — data nahi mila

{
  "success": false,
  "need_captcha": true,             // true → /captcha flow chalao
  "error": "Ye GSTIN kisi bhi record mein nahi mila. Number dobara check karo.",
  "tried": ["busy", "mastersindia", "cashfree", "tally", "pice", "khatabuddy"],
  "errors": { "busy": "...", "pice": "not found: GST not found" }
}

Official GST portal ka session kholta hai. Sirf tab use karo jab /lookup ne need_captcha: true diya ho.

Request

{ "gstin": "27AAPFU0939F1ZV" }

Response

{
  "session_id": "a1b2c3d4e5f6",
  "captcha_image": "iVBORw0KGgo...",   // base64 PNG → <img src="data:image/png;base64,...">
  "gstin": "27AAPFU0939F1ZV"
}

Admin ne captcha band kiya ho to 403. GST portal down ho to 502.

Request

{ "session_id": "a1b2c3d4e5f6", "captcha": "AB12CD" }

Response — success

{ "success": true, "taxpayer": { ...same fields as /lookup... }, "goods_service": { ... } }

Response — captcha galat

{
  "success": false,
  "error": "Enter valid letters shown in the image below",
  "session_id": "a1b2c3d4e5f6",        // same session, dobara /search karo
  "captcha_image": "iVBORw0KGgo..."     // naya captcha
}

// request
{ "session_id": "a1b2c3d4e5f6" }
// response
{ "session_id": "a1b2c3d4e5f6", "captcha_image": "iVBORw0KGgo..." }

{ "status": "ok", "active_sessions": 0 }

Field kisi source se na mile to wo response mein hoga hi nahi — code mein hamesha check karke use karo.

GSTIN format: 15 characters, e.g. 27AAPFU0939F1ZV (2 digit state + 10 PAN + entity + Z + check).

curl -X POST BASE/lookup \
  -H "Content-Type: application/json" \
  -d '{"gstin":"09ALIPB1014E2ZS"}'

async function gstLookup(gstin) {
  const res = await fetch("BASE/lookup", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ gstin }),
  });
  const j = await res.json();
  if (!res.ok) throw new Error(j.detail);          // 400: GSTIN galat
  if (j.success) return j.taxpayer;                 // ✓ done
  if (j.need_captcha) {
    // fallback: GET captcha → user ko dikhao → /search
    const c = await fetch("BASE/captcha", {
      method: "POST", headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ gstin }),
    }).then(r => r.json());
    // img.src = "data:image/png;base64," + c.captcha_image
    // then POST BASE/search { session_id: c.session_id, captcha: userInput }
  }
  throw new Error(j.error);
}

import requests

BASE = "BASE"

def gst_lookup(gstin: str) -> dict:
    r = requests.post(f"{BASE}/lookup", json={"gstin": gstin}, timeout=30)
    r.raise_for_status()                      # 400 = GSTIN galat
    j = r.json()
    if j["success"]:
        return j["taxpayer"]
    raise RuntimeError(j.get("error"))        # need_captcha → /captcha + /search

t = gst_lookup("09ALIPB1014E2ZS")
print(t["lgnm"], t["sts"], t.get("pan"))
for ret in t.get("returns", [])[:4]:
    print(ret["type"], ret["period"], ret["status"])

<?php
$ch = curl_init("BASE/lookup");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["gstin" => "09ALIPB1014E2ZS"]),
]);
$j = json_decode(curl_exec($ch), true);
if ($j["success"]) {
  echo $j["taxpayer"]["lgnm"];
} else {
  echo $j["error"];   // need_captcha true ho to /captcha + /search
}

Response yahan aayega…