Fetch GST Analysis Data

Endpoint Overview

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

Description

The Fetch GST Analysis Data API returns the complete structured payload for a completed GST analysis job. This includes the taxpayer's profile, period-wise filing status, computed analysis summary, monthly turnover/tax breakdowns, and signed URLs to downloadable PDF and Excel reports.

This is the final step in the GST Analyzer workflow (initiate → poll status → fetch data). The endpoint should only be called once the status endpoint reports status: "completed". Billing for the analysis is triggered on the first successful data fetch.

Key Benefits

Comprehensive Output — Profile, filings, computed metrics, monthly data, and report URLs in a single response.

Downloadable Reports — Ready-to-share PDF and Excel artifacts for end-customer delivery and audit trails.

Structured for Automation — JSON payload designed for direct ingestion into underwriting, risk, and accounting systems.

Idempotent Retrieval — Re-fetchable as long as the job's data retention window allows.

Use Cases

Lending & NBFC

Accounting & Audit

B2B Marketplaces

Feed analysis_summary and monthly_data into credit decisioning models for turnover-based underwriting.

Attach pdf_report_url to loan files as documentary evidence of GST compliance review.

Cross-reference reported GSTIN turnover with bank statement deposits for income verification.

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. The associated job must be in `completed` status.

Example Request

{
  "doc_id": "GST-xxxxxxxxxxxxxxxx"
}

Process Response

Response Parameters

Parameter	Type	Description
`success`	boolean	Indicates whether the data fetch succeeded.
`data`	object	Container holding the full analysis payload.
`data.doc_id`	string	The GST analysis job identifier.
`data.job_id`	string	Upstream job identifier (internal reference).
`data.status`	string	Final job status — will be `completed`.
`data.gstin`	string	GSTIN of the analyzed entity.
`data.business_name`	string	Registered business name of the entity.
`data.profile`	object	Full taxpayer profile from the GST portal (address, registration type, etc.).
`data.filing_status`	object	Per-period filing status for GSTR-1, GSTR-3B, GSTR-9, etc.
`data.analysis_summary`	object	Computed compliance and turnover metrics derived from filings.
`data.monthly_data`	array	Period-wise breakdown of returns, turnover, and tax liability.
`data.pdf_report_url`	string	Signed URL to download the PDF analysis report.
`data.excel_report_url`	string	Signed URL to download the Excel analysis report.

Example Successful Response

{
  "success": true,
  "data": {
    "doc_id": "GST-xxxxxxxxxxxxxxxx",
    "job_id": "upstream-job-id",
    "status": "completed",
    "gstin": "27AAAAA0000A1Z5",
    "business_name": "ACME Pvt Ltd",
    "profile": { },
    "filing_status": { },
    "analysis_summary": { },
    "monthly_data": [ ],
    "pdf_report_url": "https://...",
    "excel_report_url": "https://..."
  }
}

Possible Error Responses

Job Not Completed

Document Not Found

Unauthorized

Job Failed

{
  "success": false,
  "error": {
    "code": "JOB_NOT_COMPLETED",
    "message": "Analysis is still in progress. Poll the status endpoint."
  }
}

Returned when the data endpoint is called before the underlying job reaches completed status. Continue polling the status endpoint until completion.

Integration Best Practices

Security Recommendations

Always invoke this endpoint over HTTPS and validate TLS certificates.

Treat the returned profile, filing_status, and monthly_data as sensitive personal/business data; encrypt at rest and restrict access.

Download pdf_report_url and excel_report_url server-side and re-serve through your own access-controlled storage rather than exposing signed URLs to end users directly.

Set a clear retention policy for the response payload and downloaded reports in line with applicable data protection laws.

Use separate API credentials for sandbox and production environments.

User Experience Guidelines

Only call this endpoint after the status endpoint reports status: "completed" to avoid JOB_NOT_COMPLETED errors.

Present analysis_summary highlights (turnover, compliance score, filing punctuality) prominently before deep-diving into monthly_data.

Offer end users a one-click download of the PDF and Excel reports for offline review.

Surface a clear "re-run analysis" path if data appears stale, rather than letting users guess.

Localize timestamps and currency formatting for the end user's locale.

Code Samples

cURL

Python

Node.js

Related APIs

Initiate GST Analysis — Starts the asynchronous job that produces the data returned by this endpoint.

GST Analyzer Status — Polled until completion before calling this endpoint; surfaces granular processing progress.

GSTIN Verification — Lightweight synchronous endpoint for validating GSTINs without invoking a full analysis.

ITR Analyzer — Companion API for fetching and analyzing Income Tax Return filings alongside GST data.

Compliance and Legal Considerations

The response payload contains sensitive taxpayer information including GSTIN, business identifiers, filing history, and tax liability data. Handling, storage, and onward sharing of this data must comply with India's Digital Personal Data Protection Act, 2023 (DPDP Act), the Information Technology Act, 2000, and any applicable sectoral regulations (e.g., RBI guidelines for regulated lenders). Define and publish a clear retention period, restrict access on a need-to-know basis, log all access for audit purposes, and provide the underlying taxpayer with a mechanism to request data deletion in accordance with their statutory rights.

GST Data

Fetch GST Analysis Data#

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