# GST API
> Validate and decode Indian GSTINs (the 15-character Goods & Services Tax Identification Number) instantly and entirely offline. The validate endpoint checks the structure and recomputes the official GSTIN check digit — the base-36 weighted algorithm the GSTN itself uses — and confirms the embedded state code is real, returning a clear valid/invalid verdict with the specific reasons a number fails. The decode endpoint breaks a GSTIN into its parts: the GST state/UT code and its name, the embedded 10-character PAN, the PAN holder type (company, individual/proprietor, firm/LLP, HUF, trust, government and more, read from the PAN's 4th letter), the entity registration number, the default 'Z' slot and the check digit. A states endpoint returns the full GST state-code reference for building dropdowns and lookups. Everything is pure computation — no network call, no key, no cache — so it is fast and private, ideal for checkout and onboarding forms, invoicing and e-invoice/e-way-bill pipelines, vendor master data cleansing and bulk validation. A structural GSTIN validator and decoder — distinct from EU VAT-number validation (vat), IBAN bank-account validation (iban) and card-number checks (creditcard). Note: this verifies the number's structure and check digit, not whether it is actively registered in the GSTN portal. No upstream key, no cache.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/gst-api/..."
```

## Pricing
- **Free** (Free) — 2,095 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 40,300 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 213,000 calls/Mo, 20 req/s
- **Mega** ($53/Mo) — 810,000 calls/Mo, 50 req/s

## Endpoints

### GST

#### `GET /v1/decode` — Decode a GSTIN into its parts

**Parameters:**
- `gstin` (query, required, string) — The 15-char GSTIN Example: `27AAPFU0939F1ZV`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gst-api/v1/decode?gstin=27AAPFU0939F1ZV"
```

**Response:**
```json
{
    "data": {
        "gstin": "27AAPFU0939F1ZV",
        "parts": {
            "pan": "AAPFU0939F",
            "state_code": "27",
            "state_name": "Maharashtra",
            "check_digit": "V",
            "default_char": "Z",
            "entity_number": "1",
            "pan_holder_type": "Firm / LLP",
            "expected_check_digit": "V",
            "pan_holder_type_code": "F"
        },
        "valid": true,
        "format_valid": true,
        "checksum_valid": true
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:37.834Z",
        "request_id": "f8bf039f-e6a9-4042-b771-601440a1e704"
    },
    "status": "ok",
    "message": "GSTIN decoded",
    "success": true
}
```

#### `GET /v1/states` — GST state-code reference

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gst-api/v1/states"
```

**Response:**
```json
{
    "data": {
        "count": 40,
        "states": [
            {
                "code": "10",
                "name": "Bihar"
            },
            {
                "code": "11",
                "name": "Sikkim"
            },
            {
                "code": "12",
                "name": "Arunachal Pradesh"
            },
            {
                "code": "13",
                "name": "Nagaland"
            },
            {
                "code": "14",
                "name": "Manipur"
            },
            {
                "code": "15",
                "name": "Mizoram"
            },
            {
                "code": "16",
                "name": "Tripura"
            },
            {
                "code": "17",
                "name": "Meghalaya"
            },
            {
                "code": "18",
                "name": "Assam"
            },
            {
                "code": "19",
                "name": "West Bengal"
            },
            {
                "code": "20",
                "name": "Jharkhand"
            },
            {
                "code": "21",
                "name": "Odisha"
            },
            {
                "code": "22",
                "name": "Chhattisgarh"
            },
            {
                "code": "23",
                "name": "Madhya Pradesh"
            },
            {
                "code": "24",
                "name": "Gujarat"
            },
            {
         
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/validate` — Validate a GSTIN

**Parameters:**
- `gstin` (query, required, string) — The 15-char GSTIN Example: `27AAPFU0939F1ZV`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gst-api/v1/validate?gstin=27AAPFU0939F1ZV"
```

**Response:**
```json
{
    "data": {
        "gstin": "27AAPFU0939F1ZV",
        "valid": true,
        "reasons": [],
        "format_valid": true,
        "checksum_valid": true,
        "state_code_known": true
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:37.967Z",
        "request_id": "2071a744-f941-4486-bc86-d651c929265d"
    },
    "status": "ok",
    "message": "GSTIN validated",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gst-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "GST API",
        "note": "Structural validation only — this does not query the GSTN registry, so it cannot confirm a GSTIN is actively registered to a business.",
        "standard": "Indian GSTIN (15-char Goods & Services Tax Identification Number)",
        "endpoints": {
            "/v1/decode": "Decompose a GSTIN into state, PAN, holder type, entity number and check digit.",
            "/v1/states": "List all GST state/UT codes.",
            "/v1/validate": "Validate a GSTIN (format + official check digit + known state)."
        },
        "structure": "2-digit state code + 10-char PAN + 1-char entity number + 'Z' + 1-char checksum",
        "pan_holder_types": {
            "A": "Association of Persons (AOP)",
            "B": "Body of Individuals (BOI)",
            "C": "Company",
            "F": "Firm / LLP",
            "G": "Government",
            "H": "Hindu Undivided Family (HUF)",
            "J": "Artificial Juridical Person",
            "L": "Local Authority",
            "P": "Individual / Proprietor",
            "T": "Trust"
        }
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:38.052Z",
        "request_id": "bfe3cc5a-d153-4979-b34e-d221f4baae8f"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/gst-api
OpenAPI spec: https://www.oanor.com/api/gst-api/openapi.json