GST Validation API

The GST Validation API allows organizations to verify Indian GST Identification Numbers (GSTIN) against government records. It returns the taxpayer's legal name, trade name, registration status, address, and latest filing information.

Authentication

All GST endpoints require a valid PASETO token and membership in the target organization.

Endpoints

POST /api/gst/:orgId/check

Validate a GSTIN by passing it in the request body.

Path Parameters

Param	Type	Description
orgId	string	Organization ID

Request Body

Field	Type	Required	Description
gstin	string	Yes	15-character GSTIN to validate

Example Request

curl -X POST /api/gst/org_abc123/check \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "gstin": "27AAPFU0939F1ZV" }'

Response 200 OK

{
  "success": true,
  "data": {
    "gstin": "27AAPFU0939F1ZV",
    "legalName": "SUNRISE HOSPITALITY PVT LTD",
    "tradeName": "Hotel Sunrise",
    "status": "Active",
    "registrationDate": "2018-07-01",
    "taxpayerType": "Regular",
    "address": {
      "building": "Plot 42, Tower B",
      "street": "MG Road",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pincode": "400001"
    },
    "lastFilingDate": "2026-01-10",
    "lastFilingType": "GSTR-3B"
  }
}

---

GET /api/gst/:orgId/:gstId/check

Validate a GSTIN using a path-based lookup. Useful for quick verification without a request body.

Path Parameters

Param	Type	Description
orgId	string	Organization ID
gstId	string	15-character GSTIN to validate

Example Request

curl -X GET /api/gst/org_abc123/27AAPFU0939F1ZV/check \
  -H "Authorization: Bearer <token>"

Response 200 OK

Same response structure as the POST endpoint above.

---

GSTIN Format

A valid GSTIN is a 15-character alphanumeric string:

27 AAPFU0939F 1 Z V
│  │           │ │ └─ Checksum digit
│  │           │ └─── Default "Z"
│  │           └───── Entity number (1–9, A–Z)
│  └───────────────── PAN (10 characters)
└──────────────────── State code (01–37)

Position	Length	Description
1–2	2	State code
3–12	10	PAN of the taxpayer
13	1	Entity number within a state
14	1	Default — "Z"
15	1	Check digit

---

Response Fields

Field	Type	Description
gstin	string	The validated GSTIN
legalName	string	Legal (registered) name of the business
tradeName	string	Trade / brand name
status	string	Registration status: Active, Cancelled, Suspended
registrationDate	string	Date of GST registration (YYYY-MM-DD)
taxpayerType	string	Regular, Composition, SEZ, etc.
address	object	Registered address of the taxpayer
lastFilingDate	string	Date of the most recent GST return filing
lastFilingType	string	Type of the last return filed (e.g. GSTR-3B)

---

Error Responses

Status	Condition	Example Message
400	Missing or malformed GSTIN	"Invalid GSTIN format"
401	Unauthorized — missing or invalid token	"Authentication required"
403	User not a member of the organization	"Forbidden"
404	GSTIN not found in government records	"GSTIN not found"
502	Upstream GST API failure	"GST verification service unavailable"

{
  "success": false,
  "message": "Invalid GSTIN format"
}

---

Usage Notes

• Results may be cached for up to 24 hours to reduce upstream API calls.
• The GST verification service depends on an external government API; occasional timeouts are expected during peak hours.
• Both endpoints return identical response structures — choose the one that fits your client's UX pattern.