GST Verification AI Agent / LLM

# GST Verification API — Way2API®

- **Endpoint:** `POST https://app.way2api.com/api/v1/gst/verify`
- **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

## What it does

GST Verification API — Verify a 15-character GSTIN (Goods & Services Tax Identification Number) registered under India's GST system. Critical for B2B vendor verification, invoice validation, and supply chain compliance. Returns the business legal name, trade name, registration status (Active, Cancelled, Suspended), taxpayer type, constitution (Private Limited, LLP, etc.), registration date, registered address with state and pincode, PAN number, nature of business activities, and e-invoice status. Use this endpoint to validate GST invoices, verify suppliers before onboarding, and ensure regulatory compliance under GST law.

## Request body (application/json)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `gst_number` | string | yes | 15-character GSTIN — format: [0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z][Z][0-9A-Z] (e.g. 10ABCDE1234F1Z5) |

## Example request

```bash
curl -X POST https://app.way2api.com/api/v1/gst/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gst_number":"10ABCDE1234F1Z5"}'
```

## 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": {
            "gstin": "10ABCDE1234F1Z5",
            "lgnm": "EXAMPLE TRADERS PRIVATE LIMITED",
            "tradeNam": "EXAMPLE TRADERS PRIVATE LIMITED",
            "sts": "Active",
            "dty": "Regular",
            "ctb": "Private Limited Company",
            "rgdt": "16/05/2019",
            "lstupdt": "13/07/2023",
            "stj": "Saran 1",
            "ctj": "CHHAPRA RANGE",
            "panNo": "ABCDE1234F",
            "einvoiceStatus": "Yes",
            "nba": [
                "Office / Sale Office",
                "Recipient of Goods or Services",
                "Supplier of Services",
                "Retail Business"
            ],
            "pradr": {
                "addr": {
                    "bnm": "PLOT 12, GANDHI NAGAR",
                    "st": "MAIN ROAD, BLOCK-JALALPUR",
                    "loc": "JALALPUR",
                    "dst": "Saran",
                    "stcd": "Bihar",
                    "pncd": "841412"
                },
                "ntr": "Office / Sale Office, Supplier of Services"
            }
        }
    }
}
```

## Error response — 422

```json
{
    "status": "SUCCESS",
    "status_code": 422,
    "charged": true,
    "success": false,
    "message": "Invalid GSTIN / UID",
    "message_code": "VERIFICATION_FAILED",
    "order_id": "W2A1739512345abcdef01",
    "data": {
        "order_id": "W2A1739512345abcdef01",
        "error_code": "INVALID_GSTIN",
        "result": {
            "gst_number": "10ABCDE1234F2Z5A"
        }
    }
}
```

## 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.