Initiate GST Analysis

Endpoint Overview

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

Description

The Initiate GST Analysis API kicks off an asynchronous job that securely logs into the GST portal using the taxpayer's credentials and fetches historical filing data across the configured financial years. The job computes compliance metrics, builds period-wise breakdowns, and generates downloadable PDF and Excel reports.

This is the entry point of a three-step workflow: initiate → poll status → fetch full data. The response returns a unique doc_id that must be persisted by the client and used for all subsequent calls in the workflow.

Key Benefits

Automated GST Compliance Review — Eliminates manual GST portal navigation and data extraction.

Multi-Year Historical Analysis — Configurable lookback window (default 3 years) for trend detection and underwriting.

Asynchronous Processing with Webhooks — Non-blocking architecture with optional webhook callbacks for real-time updates.

Ready-to-Use Reports — Generates downloadable PDF and Excel reports alongside structured JSON data.

Use Cases

Lending & NBFC

Accounting & Audit

B2B Marketplaces

Underwriting MSME and SME loan applications by validating turnover claims against actual GST filings.

Continuous monitoring of borrower GST compliance health as part of post-disbursement risk management.

Computing GST-derived turnover for working capital and invoice discounting facilities.

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
`username`	string	Yes	GST portal login username for the taxpayer.
`password`	string	Yes	GST portal password associated with the username. Transmitted securely over TLS.
`num_years`	integer	No	Number of historical financial years to analyze. Defaults to `3` if omitted.
`financial_years`	array of strings	No	Explicit list of financial years to fetch (e.g., `"2022-23"`). When provided, overrides `num_years`.
`webhook_url`	string	No	HTTPS callback URL that will receive job status updates on completion or failure.

Example Request

{
  "username": "your_gst_username",
  "password": "your_gst_portal_password",
  "num_years": 3,
  "financial_years": ["2022-23", "2023-24", "2024-25"],
  "webhook_url": "https://your-server.com/webhook"
}

Process Response

Response Parameters

Parameter	Type	Description
`success`	boolean	Indicates whether the initiation request was accepted successfully.
`data`	object	Container holding the initiation result.
`data.doc_id`	string	Unique identifier for the GST analysis job. Persist this value — it is required for status polling and data retrieval.
`data.status`	string	Initial job status. Will be `pending` upon successful initiation.
`message`	string	Human-readable confirmation message.

Example Successful Response

{
  "success": true,
  "data": {
    "doc_id": "GST-xxxxxxxxxxxxxxxx",
    "status": "pending"
  },
  "message": "GST analysis initiated"
}

Possible Error Responses

Invalid Credentials

Unauthorized

Validation Error

Rate Limited

{
  "success": false,
  "error": {
    "code": "INVALID_GST_CREDENTIALS",
    "message": "The provided GST portal username or password is incorrect."
  }
}

Returned when the supplied username/password combination cannot authenticate against the GST portal. Verify credentials with the taxpayer before retrying.

Integration Best Practices

Security Recommendations

Never log, persist, or cache the taxpayer's password field on your servers — pass it through to the API in-memory only.

Always invoke this endpoint over HTTPS and validate TLS certificates to prevent credential interception.

Treat X-API-KEY and X-API-Secret as highly sensitive secrets; rotate them periodically and store them in a secure secret manager.

Validate that webhook_url is an HTTPS endpoint under your control and verify webhook signatures (if provided) before trusting payloads.

Use separate API credentials for sandbox and production environments.

User Experience Guidelines

Display a clear consent screen to the end user explaining that their GST portal credentials will be used to fetch filing data on their behalf.

Allow users to specify the lookback window (num_years or financial_years) where relevant to their use case rather than hard-coding defaults.

Use webhooks where possible to reduce client polling overhead.

Provide a fallback messaging path for cases where the GST portal requires OTP/MFA or credentials need to be re-entered.

Cache the returned doc_id against the user's session so the workflow can resume across page reloads.

Code Samples

cURL

Python

Node.js

Related APIs

GST Analyzer Status — Poll the processing status of an initiated analysis job using the doc_id returned by this endpoint.

GST Analyzer Data — Retrieve the full structured analysis payload, including profile, filing status, monthly data, and report URLs once the job reaches completed.

GSTIN Verification — Lightweight endpoint for validating a GSTIN and fetching basic taxpayer details without requiring portal credentials.

Compliance and Legal Considerations

This API requires the taxpayer's GST portal credentials. Integrators must obtain explicit, informed consent from the taxpayer before collecting and transmitting these credentials, in line with India's Information Technology Act, 2000 and the Digital Personal Data Protection Act, 2023 (DPDP Act). Credentials must never be stored on integrator systems and should only be passed in-transit to this endpoint. Publish a clear privacy notice describing the purpose of data collection, retention period of derived analysis data, and the user's right to withdraw consent. Use of data extracted via this API must comply with the GST portal's terms of service and the contractual agreement with Finpass.

Analyze

Initiate GST Analysis#

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