API Documentation

The main endpoint: who a GSTIN belongs to, and whether it is still active. Try it in the browser first →

Last filed return period, type, status and date for a GSTIN, one entry per return filed in the given financial year. Same auth, credits and rate limit as the main endpoint.

return_period is YYYY-MM, the month the return covers. An empty returns array means no return was filed for that GSTIN in that financial year. For whether a GSTIN files Monthly or Quarterly, use the dedicated /v1/gstin/{gstin}/filing-preference endpoint below.

Whether a GSTIN is on Monthly or Quarterly (QRMP) return filing, one entry per quarter of the financial year — a taxpayer can switch quarter to quarter, so this is not a single fixed value. Same auth, credits and rate limit as the main endpoint.

Verification, return filing history and filing frequency in one call, for 2 credits — cheaper than calling /v1/gstin/{gstin}, /returns and /filing-preference separately (3 credits total). Best-effort on filing history and filing frequency: if either cannot be fetched, those fields come back null rather than failing the whole call — you are only ever charged once verification itself succeeds.

Only need one field? /v1/gstin/{gstin}/returns and /v1/gstin/{gstin}/filing-preference above are each 1 credit on their own — use this bundle when you want all three together.

The filing history, already summarised: how many returns of each type were filed in the financial year, the last period filed, how many months ago that was, and how long after each period’s end the taxpayer typically files. One call instead of fetching/returnsand computing it yourself.

avg_filing_lag_days is measured from the end of the return period, not the statutory due date — it is a habit indicator, not a legal late-filing count. A quarterly (QRMP) filer legitimately shows 2–3 month gaps between GSTR-1 periods, so apply your own thresholds with the taxpayer’s filing frequency in mind.

The mobile number and email registered against a GSTIN, together with its legal name, status, address, city, state and PIN code read live from the GST network, so you can see whose contact it is. The GST portal’s public search does not show the contact. The same lookup as the Contact option of Bulk GSTIN Check, one GSTIN per call.

Response fields

The contact is the one on the GST registration, which may be a consultant’s, or out of date if the business changed its number without amending its registration. A mobile number and email are personal data under Indian law: use them for the business purpose you looked them up for, such as vendor onboarding, know-your-business checks or collections, and not for unsolicited marketing. More on this: GSTIN to contact details.

Today’s usage for the calling API key. Authenticated the same way, and does not consume a credit.

No 400/404/429/502 on this endpoint — there is no input to validate, no upstream call, and no rate limiter here.

A GSTIN embeds its PAN, but there is no shortcut that goes the other way. We build every mathematically valid GSTIN the PAN could hold — one per GST state code, at the first registration index — and check each one against the live network. Most PANs are registered in only a handful of states, so a not_found from most of the 36 states checked is the ordinary outcome, not an error. Only entity code “1” (the first registration) is tried per state; a second registration in the same state under the same PAN is rare enough that checking for it is not worth 35x more upstream calls by default.

Billed once per scan (1 PAN search credit, not per state checked), regardless of how many GSTINs are found — including zero.

Checks that a PAN exists and returns the registered name of its holder. Pick how much you need with level: basic (the registered name, the default), verified (also date of birth, holder category and whether an Aadhaar is linked) or details (also address and contact, as the source returns them). The masked Aadhaar number is never returned. Date of birth is returned as DD/MM/YYYY. The credit price depends on the level and your pack, from the regular credit balance. Nothing is cached.

A watchlist is a named group of GSTINs checked on a shared schedule —daily,weekly ormonthly. Create as many as you like; monitoring is priced per distinct GSTIN watched across your account, not per list. Every route on this page accepts the samex-api-keyheader as GSTIN lookups.

GET /v1/watchlists lists yours (withentry_count and 30-day critical-alert count on each).PATCH /v1/watchlists/:id renames, reschedules, pauses or resumes one. DELETE /v1/watchlists/:id removes it and every entry on it.

Send one GSTIN or an array of them. A GSTIN already on another one of your watchlists adds for free — you only pay quota for distinct GSTINs across the whole account.vendor_code andlabel are optional free text, yours to key back to your own ERP or CRM.

Up to 5,000 rows per request. Bad rows are reported individually and do not block the good ones in the same request. Over your plan’s quota, the whole request is refused with402 and the response carries your current entitlement (used / quota) rather than a bare error.

Bulk import also accepts a CSV body atPOST /v1/watchlists/:id/entries/import(content-type: text/csv, columnsgstin,vendor_code,label, header row optional).

entryId is the id returned by GET /v1/watchlists/:id/entries, not the GSTIN itself.

Every detected change for GSTINs on this watchlist — a status flip, a filing gone stale, an address change. Optional severity andsince query params filter it.

severity is one ofinfo, medium,high, critical. A CSV export of the same data is atGET /v1/watchlists/:id/events.csv.

Rather than polling /events, register an HTTPS endpoint and we POST to it as soon as changes are detected — typically within an hour. This is what you would point at an n8n, Zapier or Make webhook trigger.

Must be HTTPS and publicly reachable — no localhost or private IPs. Maximum 3 endpoints per account. Save the secret: you will need it to verify incoming payloads. GET /v1/webhooks lists your endpoints (the secret is returned again on every read), DELETE /v1/webhooks/:id removes one, and POST /v1/webhooks/:id/test fires a signed sample event at it immediately — for testing your receiver before real data flows.

The official description for any 2 to 8 digit HSN (goods) or SAC (services) code, plus the broader codes it sits under so you can show a breadcrumb without extra requests. Served from our own copy of the GST portal’s published master — typically under 50 ms.

kind is hsn for goods or sac for services. A malformed code is a 400 and an unknown one a 404 — neither is charged. Every response carriessource.refreshed_atso you can see how current the master is.

Find a code when you only know the goods or service. An exact code match ranks first, then descriptions starting with your term, then descriptions containing it — so a search for “cotton” surfaces the cotton chapter before every item that merely mentions it.

Logs in with your portal API user and does nothing else: no document is created and nothing is charged. Run it once before your first live call; most "Invalid login credentials" (error 108) failures are an API user created for a different GSP. For e-invoice, POST the same body to /v1/einvoice/credentials/test with einv_username. Limited to 3 tests per GSTIN every 15 minutes. How to create the API user: credentials setup guide.

Free: no portal credentials, no credits, and the government network is never contacted, so you can call it as often as you like. It checks the mistakes that most often get a document refused: document number and date rules, GSTIN format and state codes, pincodes, HSN, value totals, vehicle number format and missing transport details. Any signed-in key works, paid or not.

An error is a rule the government network applies without exception. A warning is a probable mistake, for example a GSTIN with a wrong check character. Passing does not guarantee acceptance: a cancelled GSTIN, a duplicate document and your portal login are only visible to the government network. When a live call is refused, the response carries a likely_causes list built by this same check, but the check never blocks a live call.

Files a real e-way bill against the government network and returns the e-way bill number.

Costs 3 credits per successful e-way bill — not per attempt.

Response fields

POST /v1/ewaybill/cancel and POST /v1/ewaybill/close take the same credentials plus ewaybill_no. A request the government network rejects (expired registration, malformed payload) is never charged — the exact error_code from the filing system is returned so you know which.

Direct lookup by document type and number — not date-scoped, so it works regardless of when the document was generated. Useful when a generate call answered “already generated” (see Safe retries below) and you want the real e-way bill number back, without guessing a date to search.

Costs 1 credit per lookup that actually reaches the government network — well under a generate call, since this is a read, not a filing. A clean "no matching document" answer is billed the same as a match, unlike a rejection elsewhere in this API, because it is still a real completed call against rate-limited upstream infrastructure. Only a request that never reaches the government network (missing fields, insufficient credits) is free.

Updates the vehicle number (and related transit details) on an e-way bill already in transit — for example when the original vehicle breaks down or goods are transhipped mid-journey.

Costs 3 credits per successful update, the same price as generate/cancel/close.

Assigns or changes the transporter on an e-way bill. Only the generator of the e-way bill can change its transporter — this is enforced by the government network.

Costs 3 credits per successful update, the same price as generate/cancel/close.

Extends the validity of an e-way bill that is about to expire, for example when a consignment is delayed in transit. The government network only allows this within a window around expiry, and requires a Part-B (vehicle) entry to exist first — use update-vehicle beforehand if there is none.

Costs 3 credits per successful extension, the same price as generate/cancel/close.

Full details of one e-way bill by its number — parties, item list, vehicle-update history. Distinct from Look up an e-way bill above, which looks up by document type + number instead of an already-known e-way bill number.

Costs 1 credit per lookup that actually reaches the government network, same as Look up an e-way bill above — a clean "no such e-way bill" answer is billed the same as a match.

Combines several e-way bills moving on one vehicle into a single consolidated e-way bill (trip sheet). You must be the generator or the assigned transporter of every e-way bill on it, and each must still be active.

Costs 3 credits per successful consolidated e-way bill, however many e-way bills it carries. A rejection is never charged.

The consolidated e-way bill (trip sheet) and every e-way bill on it, by its 10-digit number.

Costs 1 credit per lookup that actually reaches the government network, same as Get e-way bill details above.

Re-issues a consolidated e-way bill after a vehicle change. This is not an in-place edit: it returns a new consolidated e-way bill number and the previous one is cancelled. Only the generator or the current transporter can do this, and only active, unexpired e-way bills carry across.

Costs 3 credits per successful regeneration. A rejection is never charged.

The e-way bills assigned to your GSTIN as transporter, by the date they were generated. Optionally narrow to one generator’s GSTIN or state — one filter at a time, not both.

Costs 1 credit per call that actually reaches the government network, including one that returns an empty list.

Rejects an e-way bill another party generated against your GSTIN. Only the recipient can reject a document — never its own generator — and only within the government network's own rejection window, both enforced upstream.

Costs 3 credits per successful rejection, the same price as generate/cancel/close.

Cancels a previously generated e-way bill on the government network.

Costs 3 credits per successful cancellation — the same price as generating one.

Marks an e-way bill as closed once the goods movement it covers has actually happened — different from cancelling one that should never have existed.

Costs 3 credits per successful close.

Registers the invoice with the government e-invoice system and returns its IRN, acknowledgement and signed QR code. Put EwbDtls in the payload to ask for the e-way bill in the same call; ewaybill_status in the response says what happened to it.

Costs 3 credits per successful e-invoice — not per attempt.

EwbDtls: the e-way bill part of the payload

Leave a field out entirely when you do not use it. The government schema rejects empty strings, which is a common reason the IRN is issued but the e-way bill is refused.

Response fields

qr_code_image and signed_invoice are the filing system’s SignedQRCode and SignedInvoice respectively — passed through as-is, not re-rendered. qr_code_image is just the QR payload meant for printing on the invoice (you’ll need a QR-rendering library to turn it into a scannable image); signed_invoice is the full tamper-evident signed invoice record, for audit and reconciliation.

Free and offline, like the e-way bill check: no portal credentials, no credits, no call to the government network. It checks the INV-01 rules that most often cause a refusal: invoice number and date, seller and buyer GSTIN and state codes, pincodes, HSN, GST slabs, every line and document total, IGST versus CGST and SGST for the place of supply, and any embedded e-way bill details.

Errors are unambiguous rules; warnings are probable mistakes. A payload that passes can still be refused for reasons only the government network can see, and a refused live call returns a likely_causes list from this same check. The check never blocks a live call.

Cancels a previously generated e-invoice by its IRN.

Costs 3 credits per successful cancellation.

The same connection the dashboard makes, from your own server. Send the GSTIN and the GST portal username that GSTIN logs in with: not a practitioner login, and not the username of another GSTIN under the same PAN. Before the first connection the GSTIN needs API access set up on the GST portal, including the GSP-ASP combination; the GST portal API access guide has the steps and what to select. There is no test_mode here: this call sends a real OTP.

These four calls take x-api-key like every other endpoint (or the dashboard session token). None of them is charged. One connection covers GSTR-1, GSTR-3B, GSTR-2A, GSTR-2B and IMS for that GSTIN, from any IP.

Send the 6-digit OTP within 10 minutes of requesting it. A successful verify proves the username and the OTP; whether the GSTIN belongs to that username is checked by the GST network on the first data call, so a connection can show active and still answer RET11402 "API Authorization Failed" on a fetch. That response carries the remedy as fix and is not charged.

Every GSTIN connected on this account with its live status. Poll this instead of guessing whether a session is still valid.

Use it before reconnecting with a different username, or when a GSTIN should no longer be reachable from this account.

ret_period is MMYYYY. payload is the GSTR-1 JSON in the GST network's own schema (gstin, fp, b2b and so on), passed through untouched. pan is the PAN of the authorised signatory who will receive the OTP.

summary is the object /v1/gstr1/save returned, unchanged: its checksum is what the GST network signs off on. evc_otp is the six-digit OTP sent for this filing.

payload is the GSTR-3B JSON in the GST network's own schema (sup_details, inter_sup, itc_elg, intr_ltfee and so on), passed through untouched.

payload carries the ledger split in the GST network's schema: pdcash for what is paid in cash and pditc for what is paid from input credit.

Ask for the OTP just before you file; it is valid for a short time.

chksum is the checksum from /save (or from /offset, if you paid first). The return is read again before filing, and a mismatch stops the filing.

ret_period is MMYYYY. You only need this if a 2B does not already exist for the period, or you want it regenerated after suppliers filed late.

int_tran_id is the one /generate returned.

ret_period is MMYYYY. file_num (optional) identifies which generation of that period's 2B to read, if it was regenerated more than once; leave it out for the default.

ret_period is MMYYYY. table picks which of the 12 tables above to fetch — one flat price per call, regardless of table. ctin and fromtime are optional filters accepted by most tables; amdhist additionally requires portcode, benumber and bedate.