Three endpoints
| Endpoint | What it returns |
|---|---|
| GET /v1/gstin/{gstin}/returns?fy=2025-26 | Every return filed in the year: return type, period, filing date, status and ARN |
| GET /v1/gstin/{gstin}/compliance?fy=2025-26 | A summary per return type: number filed, last period filed, months since then, average filing lag |
| GET /v1/gstin/{gstin}/filing-preference?fy=2025-26 | Whether the taxpayer files monthly or quarterly, quarter by quarter |
The fy parameter is required, in the form 2025-26.
A request
curl "https://www.gstinapi.in/v1/gstin/33AAACC1206D1ZN/returns?fy=2025-26" \
-H "x-api-key: gak_your_api_key"How to read the result
The compliance summary reports facts and leaves the judgement to you. It gives no on-time percentage and no defaulter flag, because both depend on how the taxpayer is allowed to file.
A taxpayer on the quarterly scheme (QRMP) files GSTR-1 and GSTR-3B once a quarter, so a gap of two or three months in their history is normal. Check the filing preference before you read a gap as a missed return.
- Monthly filer with no GSTR-3B for three months or more: worth a question to the vendor before you pay the next invoice.
- Quarterly filer with the last quarter filed: up to date, even though recent months look empty.
- No returns at all in the year for an active GSTIN: check the registration date. A new registration may simply have nothing due yet.
What it costs
- 1 credit per successful call to any of the three endpoints.
- A malformed GSTIN, a GSTIN the GST network has no record of, and a provider failure cost nothing.
- Credits are ₹0.80 down to ₹0.40 each depending on the pack, before 18% GST. The free lookups every account starts with work here too.
- To check a whole vendor list at once, bulk verification fills in the filing frequency and the last GSTR-1 and GSTR-3B periods for every row.
Frequently asked questions
Can I check by API whether a GSTIN has filed its returns?
Yes. GET /v1/gstin/{gstin}/returns?fy=2025-26 lists every return the taxpayer filed in that financial year, with the return type, period, filing date, status and ARN.
Which returns does it cover?
Whatever the GST network reports as filed for that GSTIN in the year. For most businesses that is GSTR-1 and GSTR-3B, and other return types appear when they were filed.
Does it tell me if a vendor is a defaulter?
It gives you the facts to decide: how many returns were filed, the last period filed and the months since. It does not label anyone a defaulter, because a quarterly filer legitimately shows gaps of several months.
Why does filing status matter for input tax credit?
Your credit on a purchase depends on the supplier reporting that invoice in their returns. A supplier who has stopped filing is a supplier whose invoices may not support your claim.
What does a return filing check cost?
One credit per successful call, the same credit a GSTIN lookup uses. Calls that fail or find no such GSTIN are free.
Can I test it without spending credits?
Yes. GET /v1/gstin/00AAAAA0000A1ZT/returns?fy=2025-26 returns a sample filing history in the live response shape and is never charged. The same test GSTIN works on /compliance, /filing-preference and /complete.
Start with up to 100 free lookups
25 on signup and 25 for each of three setup steps. No card, and they never expire.
Create a free account