---
title: "GST Verification API Reference"
description: "Verify GSTIN details instantly — legal name, trade name, status, address, and filing metadata — for vendor onboarding and compliance checks."
canonical: "https://eps.eko.in/docs/verify-gstin"
---


> **Canonical URL:** https://eps.eko.in/docs/verify-gstin
> This is a machine-readable Markdown version of the page for AI agents and LLMs. The primary (HTML) version lives at the canonical URL above.

# GST Verification API Reference

`POST https://staging.eko.in/ekoapi/v3/tools/kyc/gstin`

Verify GSTIN details instantly — legal name, trade name, status, address, and filing metadata — for vendor onboarding and compliance checks.

The GST Verification API validates a GSTIN against official government records and returns the full registration profile: legal and trade names, taxpayer type, constitution of business, nature of activities, registration and last-update dates, state and centre jurisdiction, and the principal place of address (both as a flat string and as structured address components). Designed for KYB, vendor/merchant onboarding, compliance due diligence, and high-volume B2B verification pipelines.

> View product & pricing details: [GST Verification](https://eps.eko.in/products/gst-verification-api.md)

## Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| initiator_id | string | yes | Registered mobile number of the API user (see Platform Credentials). e.g. 9962981729 |
| user_code | string | yes | User code of the retailer/agent the service is run for. e.g. 20810200 |
| client_ref_id | string | no | Unique reference id per API call, generated by your system. e.g. REQ-20260101-001 |
| gstin | string | yes | Goods and Services Tax Identification Number of the business to verify (15-character alphanumeric). e.g. 29ABCDE1234F1Z5 |
| business_name | string | yes | Name of the business associated with the GSTIN (max 100 characters). Used for cross-reference in the verification response. e.g. Acme Pvt Ltd |

## Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| developer_key | string | yes | Static API key issued to your account after KYC. |
| secret-key | string | yes | Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))). |
| secret-key-timestamp | string | yes | Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time. |
| content-type | string | yes | application/json e.g. application/json |

## Response

⭐ marks fields highlighted as verifiable.

| Field | Type | Description |
| --- | --- | --- |
| status | number | Primary success indicator (0 = success). |
| message | string | Human-readable response / error message. |
| response_status_id | number | Granular status id; see the shared error-codes table. |
| response_type_id | number | A unique id for every possible response shape (success or error) — useful for client logic branching and analytics. |
| data | object | API-specific response payload. |
| data.gstin ⭐ | string | The GSTIN that was verified, echoed back from the government source. |
| data.valid ⭐ | boolean | True if the GSTIN was found and is a valid registered number; false otherwise. |
| data.gst_in_status ⭐ | string | Current registration status of the GSTIN (e.g. Active, Cancelled, Suspended). |
| data.legal_name_of_business ⭐ | string | Official legal name of the business as registered with GST authorities. |
| data.taxpayer_type ⭐ | string | Classification of the taxpayer (e.g. Regular, Composition, Non-resident, Casual Taxable Person). |
| data.constitution_of_business ⭐ | string | Legal structure / constitution of the business (e.g. Private Limited Company, Proprietorship, Partnership). |
| data.date_of_registration ⭐ | string | Date on which the GSTIN was registered (DD/MM/YYYY format). |
| data.last_update_date ⭐ | string | Date of the most recent update to the GST registration record (DD/MM/YYYY format). |
| data.cancellation_date ⭐ | string | Date of cancellation of the GST registration, if applicable. Empty string or null for active registrations. |
| data.nature_of_business_activities ⭐ | string | Comma-separated list of business activity categories as declared during GST registration (e.g. Wholesale, Supplier of Services, Recipient of Goods or Services). |
| data.state_jurisdiction ⭐ | string | State GST authority / jurisdiction under which the GSTIN is registered. |
| data.center_jurisdiction | string | Central GST authority / jurisdictional commissionerate for the registered business. |
| data.principal_place_address ⭐ | string | Principal place of business address as a single formatted string. |
| data.principal_place_split_address ⭐ | object | Principal place of business address broken into structured components. |
| data.principal_place_split_address.flat_number | string | Flat, door, or unit number. |
| data.principal_place_split_address.building_name | string | Name of the building or premises. |
| data.principal_place_split_address.street | string | Street or road name. |
| data.principal_place_split_address.location | string | Locality or neighbourhood identifier. |
| data.principal_place_split_address.city | string | City name. |
| data.principal_place_split_address.district | string | District name. |
| data.principal_place_split_address.state | string | State name. |
| data.principal_place_split_address.pincode | string | Postal / ZIP code. |
| data.principal_place_split_address.latitude | number | Geographic latitude of the principal place of business. |
| data.principal_place_split_address.longitude | number | Geographic longitude of the principal place of business. |
| data.additional_address_array | array | Array of additional registered places of business. Each element has the same structure as principal_place_split_address plus a flat address string. |
| data.additional_address_array.flat_number | string | Flat, door, or unit number of the additional address. |
| data.additional_address_array.building_name | string | Building name of the additional address. |
| data.additional_address_array.street | string | Street of the additional address. |
| data.additional_address_array.location | string | Locality of the additional address. |
| data.additional_address_array.city | string | City of the additional address. |
| data.additional_address_array.district | string | District of the additional address. |
| data.additional_address_array.state | string | State of the additional address. |
| data.additional_address_array.pincode | string | Pincode of the additional address. |
| data.message | string | Verification result message from the data source. |
| data.status_code | number | Internal status code from the upstream GST data source. |

## Example request

```json
{
  "initiator_id": "9962981729",
  "user_code": "20810200",
  "client_ref_id": "REQ-20260101-001",
  "gstin": "29ABCDE1234F1Z5",
  "business_name": "Acme Pvt Ltd"
}
```

## Example response

```json
{
  "status": 0,
  "response_status_id": 0,
  "message": "GSTIN verification successful",
  "response_type_id": 1388,
  "data": {
    "gstin": "29ABCDE1234F1Z5",
    "valid": true,
    "gst_in_status": "Active",
    "legal_name_of_business": "Acme Private Limited",
    "taxpayer_type": "Regular",
    "constitution_of_business": "Private Limited Company",
    "date_of_registration": "01/07/2017",
    "last_update_date": "01/02/2022",
    "cancellation_date": "",
    "nature_of_business_activities": "Wholesale, Supplier of Services, Recipient of Goods or Services",
    "state_jurisdiction": "Karnataka",
    "center_jurisdiction": "Commissionerate of Central Tax, Bangalore",
    "principal_place_address": "123, MG Road, Bangalore, Karnataka 560001",
    "principal_place_split_address": {
      "flat_number": "123",
      "building_name": "MG Towers",
      "street": "MG Road",
      "location": "Bangalore",
      "city": "Bangalore",
      "district": "Bangalore Urban",
      "state": "Karnataka",
      "pincode": "560001",
      "latitude": 12.9716,
      "longitude": 77.5946
    },
    "additional_address_array": [],
    "message": "GSTIN verification successful",
    "status_code": 1
  }
}
```

## Error scenarios

| Status | Scenario |
| --- | --- |
| 200 | GSTIN not found / does not exist in government records |
| 400 | Missing required field (gstin or business_name not supplied) |
| 403 | Authentication failure — wrong or expired secret-key / timestamp |