GST Analyzer Job Status

Endpoint Overview

POST /api/v1/services/gst-analyzer/status

Description

The GST Analyzer Status API returns the current processing state of an asynchronous GST analysis job initiated via the /analyze endpoint. Clients should poll this endpoint at a reasonable cadence (typically every 5–10 seconds) until the job reaches a terminal state — either completed or failed — and then proceed to fetch the full analysis payload using the data endpoint.

The response exposes granular progress information including the current processing step, completed steps, failed steps, and (once available) the extracted GSTIN and business name. This enables clients to render real-time progress UIs and surface meaningful status to end users.

Key Benefits

Granular Progress Tracking — Inspect current_step and steps_completed to drive progress indicators.

Early Visibility into Job Outcome — Detect failures and the failing step before fetching final data.

Lightweight Polling — Lean response payload designed for frequent status checks.

Billing-Friendly — Polling is not billable; billing is triggered only on first successful completed data fetch.

Use Cases

Lending & NBFC

Accounting & Audit

B2B Marketplaces

Drive real-time loan application status screens during borrower onboarding.

Trigger downstream underwriting workflows the moment a GST analysis completes.

Alert operations teams when long-running jobs stall or fail at a specific step.

Technical Implementation

Authentication

All API requests require authentication using API key headers. Authentication follows these steps:

Obtain API Credentials: Register with Finpass to receive your X-API-KEY and X-API-Secret.

Include in Requests: Add both headers to every request — X-API-KEY: <your_key> and X-API-Secret: <your_secret>.

Use Environment-Specific Credentials: Use separate keys for sandbox and production.

The production environment base URL is:

Production: https://api.finpass.ai

Never expose API credentials in client-side code; always proxy requests through your backend.

Request Parameters

Request Headers

Header	Required	Description
`X-API-KEY`	Yes	Your Finpass-issued API key.
`X-API-Secret`	Yes	Your Finpass-issued API secret paired with the key.
`Content-Type`	Yes	Must be set to `application/json`.

Request Body

Parameter	Type	Required	Description
`doc_id`	string	Yes	The unique job identifier returned by the `/analyze` endpoint.

Example Request

{
  "doc_id": "GST-xxxxxxxxxxxxxxxx"
}

Process Response

Response Parameters

Parameter	Type	Description
`success`	boolean	Indicates whether the status request succeeded.
`data`	object	Container holding job status fields.
`data.doc_id`	string	The GST analysis job identifier.
`data.job_id`	string	Upstream job identifier (internal reference).
`data.status`	string	Current job status. One of: `pending`, `processing`, `completed`, `failed`.
`data.gstin`	string \| null	Extracted GSTIN once profile fetch completes; `null` before then.
`data.business_name`	string \| null	Extracted business name once profile fetch completes; `null` before then.
`data.current_step`	string	The processing step currently in progress (e.g., `fetching_returns`).
`data.steps_completed`	array of strings	List of processing steps that have completed successfully.
`data.steps_failed`	array of strings	List of processing steps that failed.
`data.error_message`	string \| null	Error description if the job failed; otherwise `null`.
`data.financial_years`	array of strings	Financial years included in the analysis once known.
`data.created_at`	string	ISO timestamp when the job was created.
`data.updated_at`	string	ISO timestamp of the last status update.
`data.completed_at`	string \| null	ISO timestamp when the job completed; `null` if still running.

Example Successful Response

{
  "success": true,
  "data": {
    "doc_id": "GST-xxxxxxxxxxxxxxxx",
    "job_id": "upstream-job-id",
    "status": "processing",
    "gstin": null,
    "business_name": null,
    "current_step": "fetching_returns",
    "steps_completed": ["login", "profile"],
    "steps_failed": [],
    "error_message": null,
    "financial_years": [],
    "created_at": "...",
    "updated_at": "...",
    "completed_at": null
  }
}

Possible Error Responses

Document Not Found

Unauthorized

Validation Error

Rate Limited

{
  "success": false,
  "error": {
    "code": "DOC_NOT_FOUND",
    "message": "No analysis job exists for the supplied doc_id."
  }
}

Returned when the supplied doc_id does not exist or belongs to a different tenant. Verify that the doc_id was captured correctly from the /analyze response.

Integration Best Practices

Security Recommendations

Always invoke this endpoint over HTTPS and validate TLS certificates.

Treat X-API-KEY and X-API-Secret as highly sensitive secrets; rotate them periodically.

Never expose the doc_id to untrusted clients; it should only be used in trusted server-to-server contexts.

Implement IP allowlisting on your backend for outbound calls to Finpass where feasible.

Use separate API credentials for sandbox and production environments.

User Experience Guidelines

Poll at a sensible interval (5–10 seconds is typical); avoid aggressive sub-second polling.

Drive a progress bar or step indicator from current_step and steps_completed to keep users informed.

When webhook_url is configured during initiation, prefer webhook callbacks over polling.

On failed status, surface a clear, user-friendly explanation derived from error_message and the failing step.

Implement a maximum polling duration with a graceful timeout if a job stalls beyond expected SLA.

Code Samples

cURL

Python

Node.js

Related APIs

Initiate GST Analysis — Starts the asynchronous job and returns the doc_id required by this endpoint.

GST Analyzer Data — Retrieves the full analysis payload once this endpoint reports status: "completed".

GSTIN Verification — Lightweight, synchronous endpoint for basic GSTIN validation without credentials.

Compliance and Legal Considerations

While this endpoint does not handle GST portal credentials directly, it returns identifying information about the taxpayer (GSTIN, business name) once available. Treat all returned data as sensitive personal/business information under the Digital Personal Data Protection Act, 2023 (DPDP Act). Restrict access to authorized personnel only, log access for audit purposes, and never persist the response beyond what is required to complete the user's workflow.

Status

GST Analyzer Job Status#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses