# GSTIN Verification (India GST) (`tuneful_champion/gstin-verification`) Actor

Bulk-verify Indian GSTINs: legal name, trade name, registration status, taxpayer type, and address, sourced live from the GST network.

- **URL**: https://apify.com/tuneful\_champion/gstin-verification.md
- **Developed by:** [Tarun Vaghasia](https://apify.com/tuneful_champion) (community)
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## GSTIN Verification (India GST)

Verify a list of Indian GSTINs in one run. For each GST number you get the registered legal name, trade name, **active / cancelled / suspended status**, taxpayer type, registration date, cancellation date and address, read live from the GST network. Export the result as JSON, CSV or Excel from the dataset.

Built on [gstinapi.in](https://www.gstinapi.in), a REST API for GSTIN verification. Nothing is served from a cache, so a registration cancelled this morning shows as cancelled.

### What you can use it for

- Check a vendor list before you claim input tax credit, and find cancelled or suspended suppliers.
- Clean a customer or party master: catch mistyped GSTINs and the legal name each number really belongs to.
- Verify GST numbers as part of onboarding, KYC or a marketplace seller check.

### Try it first, with no key

Run the Actor with its default input. It checks the sandbox number `00AAAAA0000A1ZT`, returns a fixed sample result marked `"demo": true`, and uses no credit. It shows the exact shape of the output before you sign up.

### How to use it

1. Get a free API key at [gstinapi.in/register](https://www.gstinapi.in/register). Every account starts with up to 100 free lookups (25 on signup, 25 for each of three setup steps), with no card, and credits never expire.
2. Paste the key into **gstinapi.in API key**. It is stored as a secret.
3. Paste your GSTINs, one per line, and run.

### Input

| Field | Required | Description |
|---|---|---|
| `apiKey` | For real GSTINs | Your gstinapi.in API key. Leave it empty to run only the free sandbox demo. |
| `gstins` | Yes | The 15-character GSTINs to verify, one per line. |
| `includeProfile` | No | Adds jurisdiction codes, e-invoicing status, nature of business and additional places of business, at no extra credit cost. |

### Output

One flat row per GSTIN:

```json
{
  "gstin": "27AAPFU0939F1ZV",
  "success": true,
  "legal_name": "EXAMPLE PRIVATE LIMITED",
  "trade_name": "EXAMPLE PVT LTD",
  "status": "Active",
  "taxpayer_type": "Regular",
  "registration_date": "2017-07-01",
  "cancellation_date": null,
  "state_code": "27",
  "address": "SHOP NO. 12, 1ST FLOOR, 123 BUSINESS PARK, MUMBAI",
  "pincode": "400001",
  "block_status": "Unblocked",
  "credits_remaining": 96,
  "response_ms": 412,
  "checked_at": "2026-09-20T10:15:30.000Z"
}
```

The example values are illustrative. The full field reference is at [gstinapi.in/docs](https://www.gstinapi.in/docs); with `includeProfile` on, the extra profile fields are added to the same row.

A GSTIN that could not be verified still gets a row, so a run never silently drops a number:

```json
{ "gstin": "27AAAAA0000A1Z5", "success": false, "http_status": 404, "error": "GSTIN not found in GST database", "checked_at": "2026-09-20T10:15:31.000Z" }
```

### What it costs

- Each GSTIN that resolves uses **one credit** from your gstinapi.in account. This Actor adds no charge of its own; you pay Apify only for the platform usage of the run, which is small.
- Malformed numbers, numbers the GST network has no record of, and provider errors are **not charged**.
- The same GSTIN listed twice is looked up once, so you are not charged twice. Malformed numbers are rejected before any request is made.
- Credit packs start at ₹199 for 250 lookups and fall to ₹0.40 a lookup on the largest pack, before 18% GST. See [gstinapi.in/pricing](https://www.gstinapi.in/pricing).

### Speed and limits

The API allows 60 requests a minute per key, so a run verifies roughly 50 GSTINs a minute; 1,000 GSTINs take about 20 minutes. Rate limit responses (429) and temporary upstream errors (502) are retried up to three times with backoff. If your key is invalid or out of credits, the run stops after the first failure instead of failing every remaining number.

### FAQ

**Does it tell me whether a vendor still files GST returns?** This Actor returns registration details and status. Return filing history is available from the same gstinapi.in key through its API and its bulk Excel check; see [gstinapi.in/gst-verification-api](https://www.gstinapi.in/gst-verification-api).

**Is the data live?** Yes. Every lookup queries the GST network when you run it.

**Can I call this from an AI agent instead of running batches?** Yes. gstinapi.in also has an MCP server, [gstinapi-mcp](https://github.com/CsoftTarun/gstinapi-mcp), for Claude and other MCP clients.

**Something looks wrong.** Write to us at [gstinapi.in/contact](https://www.gstinapi.in/contact).

# Actor input Schema

## `apiKey` (type: `string`):

Your gstinapi.in key. Free at https://www.gstinapi.in/register: up to 100 free lookups (25 on signup, 25 for each of three setup steps), no card. Each lookup consumes one credit. Leave this empty to run the built-in demo on the sandbox GSTIN 00AAAAA0000A1ZT, which needs no key and uses no credit.

## `gstins` (type: `array`):

One or more 15-character GSTINs, one per line. The pre-filled 00AAAAA0000A1ZT is a sandbox number that returns a fixed sample result for free; replace it with real GSTINs and add your API key.

## `includeProfile` (type: `boolean`):

Adds jurisdiction codes, e-invoicing status, and additional places of business — no extra credit cost.

## Actor input object example

```json
{
  "gstins": [
    "00AAAAA0000A1ZT"
  ],
  "includeProfile": false
}
```

# Actor output Schema

## `results` (type: `string`):

The verified GSTINs as a table. Download as JSON, CSV or Excel from the dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "gstins": [
        "00AAAAA0000A1ZT"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("tuneful_champion/gstin-verification").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "gstins": ["00AAAAA0000A1ZT"] }

# Run the Actor and wait for it to finish
run = client.actor("tuneful_champion/gstin-verification").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "gstins": [
    "00AAAAA0000A1ZT"
  ]
}' |
apify call tuneful_champion/gstin-verification --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tuneful_champion/gstin-verification"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Na2iwOby3ervqzfEV/builds/sRlvd2HTnsL251CKm/openapi.json