GST Filing Details AI Agent / LLM

# GST Filing Details API — Way2API®

- **Endpoint:** `POST https://app.way2api.com/api/v1/gst/filing-details`
- **Auth:** `Authorization: Bearer YOUR_API_KEY` (or `X-API-Key: YOUR_API_KEY`)
- **Content-Type:** `application/json`
- **Category:** Business
- **Availability:** Available in India
- **Docs:** https://app.way2api.com/documentation/gst-filing-details

## What it does

GST Filing Details API — Every GST return a GSTIN filed in one financial year, read from the government record. Send a GSTIN and a year such as 2023-24 and receive one entry per return: the form (GSTR-1, GSTR-3B, GSTR-9, CMP-08 and the rest), the tax period as YYYY-MM, the ARN acknowledgement number, the date of filing as an ISO date, whether it was filed online or offline, and its status. This is how you check a counterparty's GST return filing status and compliance history before extending credit, onboarding a supplier, or claiming input tax credit — ITC depends on the supplier having actually filed, and a gap in GSTR-1 or GSTR-3B is the earliest signal that it is at risk. Entries are returned most recent tax period first, and filing_count reports how many were found for the year.

## Request body (application/json)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `gst_number` | string | yes | 15-character GSTIN, e.g. 03DOXPM4071K1ZE. Case-insensitive. |
| `financial_year` | string | yes | Indian financial year (April to March), 2017-18 onwards. Accepts 2023-24, 2023-2024 or 202324. |

## Example request

```bash
curl -X POST https://app.way2api.com/api/v1/gst/filing-details \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gst_number":"03DOXPM4071K1ZE","financial_year":"2023-24"}'
```

## Success response — 200

```json
{
    "status": "SUCCESS",
    "status_code": 200,
    "charged": true,
    "success": true,
    "message": "",
    "message_code": "OK",
    "order_id": "W2A1739512345abcdef01",
    "data": {
        "order_id": "W2A1739512345abcdef01",
        "result": {
            "gst_number": "03DOXPM4071K1ZE",
            "financial_year": "2023-24",
            "filing_count": 16,
            "filings": [
                {
                    "return_type": "GSTR1",
                    "return_period": "2024-03",
                    "arn": "AA030324078315H",
                    "filed_on": "2024-04-08",
                    "filing_mode": "online",
                    "status": "filed",
                    "is_valid": true
                },
                {
                    "return_type": "GSTR3B",
                    "return_period": "2024-03",
                    "arn": "AA0303244598718",
                    "filed_on": "2024-04-19",
                    "filing_mode": "online",
                    "status": "filed",
                    "is_valid": true
                },
                {
                    "return_type": "GSTR1",
                    "return_period": "2024-02",
                    "arn": "AA0302241450008",
                    "filed_on": "2024-03-10",
                    "filing_mode": "online",
                    "status": "filed",
                    "is_valid": true
                }
            ]
        }
    }
}
```

## Error response — 422

```json
{
    "status": "SUCCESS",
    "status_code": 422,
    "charged": true,
    "success": false,
    "message": "Invalid GSTIN",
    "message_code": "VERIFICATION_FAILED",
    "order_id": "W2A1739512345abcdef01",
    "data": {
        "order_id": "W2A1739512345abcdef01",
        "error_code": "INVALID_GSTIN",
        "result": {
            "gst_number": "03DOXPM4071K1ZZ",
            "financial_year": "2023-24",
            "filing_count": 0,
            "filings": []
        }
    }
}
```

## Integration rules

- Every response is JSON carrying `status`, `status_code`, `charged`, `success`, `message`, `message_code` and (once a call reaches the provider) `order_id`. The verification payload is under `data.result`.
- `charged` (boolean) is the authority on billing. Do NOT infer it from the HTTP status: `422` is returned both for input we rejected (not charged) and for a lookup the provider ran and billed us for that returned a negative result (charged).
- `message_code` is a fixed vocabulary — branch on it instead of parsing `message`. Values: `OK`, `ACCEPTED`, `PROVIDER_NO_RESPONSE`, `VERIFICATION_FAILED`, `NO_RECORD_FOUND`, `INVALID_INPUT`, `REQUEST_FAILED`, `MISSING_API_KEY`, `INVALID_API_KEY`, `INSUFFICIENT_BALANCE`, `NO_API_ACCESS`, `NOT_FOUND`, `RATE_LIMITED`, `INTERNAL_ERROR`, `PROVIDER_UNAVAILABLE`.
- `success` reports the verification outcome; `status` reports the ORDER lifecycle (`SUCCESS`/`PENDING`/`FAILED`). They differ on a charged negative result: the order completed and was billed while the verification did not pass.
- A failed verification is still a successful HTTP call — the outcome lives in the response body, so do not treat `200` as "verified".
- Status codes: `200` result returned, `202` pending or provider did not respond (both charged — quote the `order_id`), `401` missing/invalid key, `402` insufficient balance, `403` no access to this service, `422` see `charged`, `429` rate limited (honour the `Retry-After` header), `503` temporarily unavailable.
- Rate limits are per API key, per service, on a 1-minute sliding window.
- Load the API key from an environment variable or secret store. Never hard-code it, never commit it, and never ship it in client-side code — calls must be made from your backend.