# Gstin-scraper (`mikolabs/gstin-scraper`) Actor Verify Indian GST numbers and retrieve comprehensive taxpayer information from the official GST portal. Retrieves GSTIN overview, business details, goods & services, HSN, and filing details. - **URL**: https://apify.com/mikolabs/gstin-scraper.md - **Developed by:** [mikolabs](https://apify.com/mikolabs) (community) - **Categories:** Developer tools, Automation, Other - **Stats:** 28 total users, 3 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $4.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## GST Verification API - India GST Portal [![Apify](https://img.shields.io/badge/Apify-Actor-blue)](https://apify.com) [![Python](https://img.shields.io/badge/Python-3.11+-green)](https://www.python.org/) An automated Apify actor that verifies Indian GST (Goods and Services Tax) numbers and retrieves comprehensive taxpayer information from the official GST portal. This actor features automatic captcha solving, intelligent retry mechanisms, and structured data output - making GST verification seamless and reliable. ### 🚀 Key Features - ✅ **Automatic Captcha Solving** - Uses AI-powered Gradio API to solve captchas automatically - ✅ **Intelligent Retry Logic** - Automatically retries failed captcha solving and data retrieval - ✅ **Data Validation** - Retries verification if data is incomplete (all N/A values) - ✅ **Structured Output** - Clean, organized JSON output with taxpayer details, address, and additional info - ✅ **Zero Manual Intervention** - Only requires GSTIN - no manual captcha solving needed - ✅ **Comprehensive Data** - Retrieves legal name, trade name, registration date, status, address, jurisdiction, and more - ✅ **Error Handling** - Robust error handling with detailed error messages - ✅ **Session Management** - Automatic session handling with the GST portal ### 📋 Input The actor requires only the GSTIN number. All other parameters are optional: ```json { "GSTIN": "07AAECD1686J1ZG", "captchaRetryAttempts": 3, "maxRetryAttempts": 3 } ```` #### Input Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | **GSTIN** | string | ✅ Yes | - | The GST Identification Number to verify (15 characters). Format: `07AAECD1686J1ZG` | | **captchaRetryAttempts** | integer | ❌ No | 3 | Number of times to retry captcha solving if it fails (range: 1-5) | | **maxRetryAttempts** | integer | ❌ No | 3 | Maximum number of times to retry GST verification if data is all N/A (range: 1-10) | #### GSTIN Format - **Length**: 15 characters - **Format**: `[State Code (2 digits)][PAN (10 chars)][Entity Number][Z][Check Digit]` - **Example**: `07AAECD1686J1ZG` - `27` = State Code (Maharashtra) - `CEGPN9391P` = PAN Number - `1` = Entity Number - `Z` = Fixed character - `F` = Check Digit ### 📤 Output The actor outputs structured GST verification data in JSON format. #### Success Response ```json { "gstin": "07AAECD1686J1ZG", "status": "success", "message": "GST verification completed successfully", "verificationDate": "16/06/2024", "verificationAttempts": 1, "taxpayerDetails": { "legalName": "NILESH LAXMANRAO NIMBALKAR", "tradeName": "SHRI SWAMI SAMARTH CONTRACT WORKS", "registrationDate": "16/06/2024", "status": "Active", "businessType": "Regular", "centerJurisdiction": "State - CBIC,Zone - NAGPUR,Commissionerate - NAGPUR II,Division - DIVISION CITY,Range - RANGE -I (Jurisdictional Office)", "stateJurisdiction": "State - Maharashtra,Zone - Nagpur,Division - NAGPUR_EAST,Charge - AJNI_701" }, "address": { "fullAddress": "PLOT NO 74, ZINGABAI TAKDI, New Mankapur Road, SAI NAGAR, Manak Pur, Nagpur, Nagpur, Maharashtra, 440030", "principalPlace": "PLOT NO 74", "buildingName": "PLOT NO 74", "street": "ZINGABAI TAKDI, New Mankapur Road", "location": "ZINGABAI TAKDI", "district": "Nagpur", "state": "Maharashtra", "pincode": "440030" }, "additionalInfo": { "centerJurisdiction": "State - CBIC,Zone - NAGPUR,Commissionerate - NAGPUR II,Division - DIVISION CITY,Range - RANGE -I (Jurisdictional Office)", "stateJurisdiction": "State - Maharashtra,Zone - Nagpur,Division - NAGPUR_EAST,Charge - AJNI_701", "constitutionOfBusiness": "Proprietorship", "natureOfBusiness": ["Works Contract", "Others"], "aadhaarVerified": "Yes", "aadhaarVerificationDate": "20/01/2025", "eKYCVerified": "Not Applicable", "eInvoiceStatus": "No", "cancellationDate": "N/A" }, "rawData": { // Complete raw response from GST portal } } ``` #### Captcha Required Response If automatic captcha solving fails after all retry attempts: ```json { "gstin": "07AAECD1686J1ZG", "captchaImage": "data:image/png;base64,...", "status": "captcha_required", "message": "Automatic captcha solving failed after 3 attempts. Last error: ...", "error": "Error details", "attempts": 3, "verificationAttempts": 3 } ``` #### Error Response ```json { "gstin": "07AAECD1686J1ZG", "status": "error", "error": "Error message", "message": "GST verification failed: Error message", "verificationAttempts": 3 } ``` ### 🔄 How It Works 1. **Session Initialization** - Creates a session with the official GST portal 2. **Captcha Fetching** - Retrieves a captcha image from the GST portal 3. **Automatic Captcha Solving** - Uses AI-powered Gradio API to solve captcha automatically 4. **GST Verification** - Submits GSTIN and solved captcha to the GST portal 5. **Data Validation** - Checks if retrieved data is valid (not all N/A) 6. **Retry Logic** - If data is incomplete, automatically retries with a new captcha 7. **Structured Output** - Formats and returns comprehensive GST details #### Retry Mechanisms - **Captcha Retry**: If captcha solving fails, retries up to `captchaRetryAttempts` times (default: 3) - **Data Validation Retry**: If retrieved data is all N/A, retries the entire verification process up to `maxRetryAttempts` times (default: 3) - **Automatic Fresh Captcha**: Each retry fetches a new captcha for better success rate ### 💻 Usage #### Using Apify Console 1. Go to [Apify Console](https://console.apify.com/) 2. Search for "GST Verification API - India GST Portal" 3. Click "Run" on the actor 4. Enter your GSTIN in the input form 5. (Optional) Adjust retry attempts if needed 6. Click "Start" to run the actor 7. View results in the dataset tab #### Using Apify API (Python) ```python from apify_client import ApifyClient ## Initialize the ApifyClient client = ApifyClient("YOUR_API_TOKEN") ## Prepare the actor input run_input = { "GSTIN": "07AAECD1686J1ZG", "captchaRetryAttempts": 3, # Optional "maxRetryAttempts": 3 # Optional } ## Run the actor run = client.actor("YOUR_USERNAME/gst-verification-india").call(run_input=run_input) ## Fetch results from the default dataset for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) ``` #### Using Apify API (JavaScript/Node.js) ```javascript const { ApifyClient } = require('apify-client'); // Initialize the ApifyClient const client = new ApifyClient({ token: 'YOUR_API_TOKEN', }); // Prepare the actor input const runInput = { GSTIN: "07AAECD1686J1ZG", captchaRetryAttempts: 3, // Optional maxRetryAttempts: 3 // Optional }; // Run the actor const run = await client.actor("YOUR_USERNAME/gst-verification-india").call(runInput); // Fetch results from the default dataset const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` #### Using cURL ```bash curl -X POST \ https://api.apify.com/v2/acts/YOUR_USERNAME~gst-verification-india/runs \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "GSTIN": "07AAECD1686J1ZG", "captchaRetryAttempts": 3, "maxRetryAttempts": 3 }' ``` ### 📊 Output Schema The actor outputs data following a structured schema defined in `.actor/dataset_schema.json`. The output includes: - **Basic Info**: GSTIN, status, message, verification date - **Taxpayer Details**: Legal name, trade name, registration date, status, business type, jurisdiction - **Address**: Full address with parsed components (building, street, location, district, state, pincode) - **Additional Info**: Constitution, nature of business, verification statuses, eInvoice status - **Raw Data**: Complete original response from GST portal for reference ### ⚠️ Limitations - **Rate Limiting**: The GST portal may apply rate limiting based on their policies - **Captcha Success Rate**: Automatic captcha solving success rate depends on image complexity - **Internet Connection**: Requires a valid internet connection to access the GST portal - **GST Portal Availability**: Depends on the GST portal being accessible and operational ### 🔒 Privacy & Compliance - This actor only accesses publicly available GST verification data - No personal sensitive data is stored beyond what's necessary for verification - Users are responsible for ensuring compliance with GST portal terms of service - This actor is for legitimate verification purposes only ### 📝 Changelog #### Version 1.0 - Initial release - Automatic captcha solving using Gradio API - Intelligent retry logic for captcha and data retrieval - Structured output format - Data validation and retry mechanism ### 🤝 Support For issues, questions, or contributions: - Open an issue on the repository - Contact through Apify Console - Check the actor's documentation in Apify Store ### 📄 License This project is provided as-is for educational and legitimate business purposes. Please ensure compliance with the GST portal's terms of service and all applicable laws and regulations. ### ⚖️ Disclaimer This actor is for legitimate GST verification purposes only. Users are responsible for: - Ensuring compliance with all applicable laws and regulations - Respecting the GST portal's terms of service - Using the actor responsibly and ethically - Verifying the accuracy of retrieved data independently The developers and maintainers of this actor are not responsible for any misuse or non-compliance with applicable laws and regulations. # Actor input Schema ## `gstins` (type: `array`): GST Identification Numbers to verify. Add one or more GSTINs (15 characters each, e.g., 07AAECD1686J1ZG). ## `extractFilingDetails` (type: `boolean`): Whether to extract filing status and return details for each financial year (default: true) ## `extractHsnCodes` (type: `boolean`): Whether to extract HSN/SAC codes and services (default: true) ## `fromYear` (type: `integer`): Optional: Filter filing details from this financial year onwards (e.g., 2020). If not provided, returns all available years. Financial years are from April to March (e.g., 2020 means FY 2020-21). Minimum: 2017 (GST introduction year). ## `captchaRetryAttempts` (type: `integer`): Number of times to retry captcha solving if it fails (default: 3, range: 1-5) ## `maxRetryAttempts` (type: `integer`): Maximum number of times to retry GST verification if data is all N/A (default: 3, range: 1-10) ## Actor input object example ```json { "gstins": [ "07AAECD1686J1ZG" ], "extractFilingDetails": true, "extractHsnCodes": true, "captchaRetryAttempts": 3, "maxRetryAttempts": 3 } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "gstins": [ "07AAECD1686J1ZG" ] }; // Run the Actor and wait for it to finish const run = await client.actor("mikolabs/gstin-scraper").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "gstins": ["07AAECD1686J1ZG"] } # Run the Actor and wait for it to finish run = client.actor("mikolabs/gstin-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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": [ "07AAECD1686J1ZG" ] }' | apify call mikolabs/gstin-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=mikolabs/gstin-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Gstin-scraper", "description": "Verify Indian GST numbers and retrieve comprehensive taxpayer information from the official GST portal. Retrieves GSTIN overview, business details, goods & services, HSN, and filing details.", "version": "1.0", "x-build-id": "hHqLKRmiQCpamc2ZH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mikolabs~gstin-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mikolabs-gstin-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/mikolabs~gstin-scraper/runs": { "post": { "operationId": "runs-sync-mikolabs-gstin-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/mikolabs~gstin-scraper/run-sync": { "post": { "operationId": "run-sync-mikolabs-gstin-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "gstins": { "title": "GSTINs", "type": "array", "description": "GST Identification Numbers to verify. Add one or more GSTINs (15 characters each, e.g., 07AAECD1686J1ZG).", "items": { "type": "string", "pattern": "^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$", "minLength": 15, "maxLength": 15 }, "default": [ "07AAECD1686J1ZG" ] }, "extractFilingDetails": { "title": "Extract Filing Details", "type": "boolean", "description": "Whether to extract filing status and return details for each financial year (default: true)", "default": true }, "extractHsnCodes": { "title": "Extract HSN/SAC Codes", "type": "boolean", "description": "Whether to extract HSN/SAC codes and services (default: true)", "default": true }, "fromYear": { "title": "Filter From Year", "minimum": 2017, "type": "integer", "description": "Optional: Filter filing details from this financial year onwards (e.g., 2020). If not provided, returns all available years. Financial years are from April to March (e.g., 2020 means FY 2020-21). Minimum: 2017 (GST introduction year)." }, "captchaRetryAttempts": { "title": "Captcha Retry Attempts", "minimum": 1, "maximum": 5, "type": "integer", "description": "Number of times to retry captcha solving if it fails (default: 3, range: 1-5)", "default": 3 }, "maxRetryAttempts": { "title": "Max Retry Attempts for Data Retrieval", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum number of times to retry GST verification if data is all N/A (default: 3, range: 1-10)", "default": 3 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```