GSTIN Scraper

This actor verifies GST registrations using the official GST Portal and emits one rich, truthful dataset record only after the protected taxpayer response returns the requested GSTIN. It can also collect the official HSN/SAC, financial-year, filing-preference and filing-history endpoints.

Required configuration

captchaSolverApiKey is required for protected taxpayer lookup. It is treated as a secret in the Actor UI and is never written to logs or output. Alternatively set CAPTCHA_API_KEY as an Actor environment variable. The solver endpoint is environment-only (CAPTCHA_API_URL) so ordinary run input cannot redirect an environment secret to another host. CAPTCHA_API_URL must use HTTPS. The model can be selected with captchaModelId or CAPTCHA_MODEL_ID.

Missing solver configuration is rejected before any proxy, browser, or GST Portal request is created. This Actor integrates with the configured solver but does not implement or bypass CAPTCHA solving.

Every taxpayer lookup downloads a fresh CAPTCHA image in the same browser session and submits it with the same session cookie. SWEB_9000 is retried with a new image up to maxCaptchaAttempts (default 3, maximum 8). If verification fails, the actor logs the exact blocker and emits no fake error row.

Input

Field	Purpose
gstins	Required GSTIN list. Values are uppercased, validated and deduplicated in order.
extractHsnCodes	Fetch official goods and services / HSN-SAC records.
extractFilingDetails	Fetch financial years, filing preferences and return records.
captchaSolverApiKey	Secret solver credential, or use CAPTCHA_API_KEY.
captchaModelId	Solver model identifier; can also be set through CAPTCHA_MODEL_ID.
maxCaptchaAttempts	Fresh CAPTCHA attempts from 1 to 8.
proxyConfiguration	Direct, rotating, or fixed Apify Proxy access. Residential India proxy is recommended.
proxySessionId	Optional validated session label for fixed proxy mode.
fingerprintProfile	Coherent Chrome Windows or macOS browser profile.

Example input

{
  "gstins": ["06AAICK7471J1Z4"],
  "extractHsnCodes": true,
  "extractFilingDetails": true,
  "maxCaptchaAttempts": 3,
  "headless": true,
  "captchaSolverApiKey": "YOUR_SOLVER_KEY"
}

Output

Verified rows include legal and trade names, taxpayer status/type, registration and cancellation values, Aadhaar/eKYC/e-invoice indicators, activities, structured/geocoded principal address, parsed state and central jurisdiction parts, HSN/SAC goods/services, financial years, filing frequency/history/counts, and source/API/proxy/fingerprint/timestamp provenance. Blank, null and empty values are omitted rather than fabricated.

The actor never exposes solver credentials and never emits a placeholder record for a failed CAPTCHA, blocked request, or GSTIN mismatch. It writes an OUTPUT summary on every terminal path. Zero verified rows cause a failed run; mixed results are explicitly marked partial and also fail so monitoring cannot mistake them for complete success.

Example output

{
  "gstinNumber": "06AAICK7471J1Z4",
  "legalName": "Example Foods Private Limited",
  "tradeName": "Example Foods",
  "status": "Active",
  "taxpayerType": "Regular",
  "registrationDate": "2020-01-15",
  "formattedAddress": "Example address, Rajasthan",
  "goodsCount": 2,
  "servicesCount": 1,
  "sourceUrl": "https://www.gst.gov.in/",
  "fetchedAt": "2026-08-18T00:00:00.000Z"
}

Local verification

Run npm test, npm run lint, then an apify run with a legitimate solver key. Use npm run validate-dataset after the run; it rejects empty values, undeclared/reserved fields, type errors, invalid GSTINs and missing provenance.