ITR Analyzer — Poll Status

POST /api/v1/itr-analyzer/status

Description

The ITR Analyzer Poll Status API returns the current processing state of an ITR analysis job. After initiating analysis via the /analyze endpoint, call this endpoint at regular intervals using the job_id to determine when the extraction and analysis is complete and the full ITR data is ready to retrieve.

Once the status reaches completed, the structured ITR analysis is available via the Get Full Data endpoint.

Key Benefits

Track ITR extraction and analysis progress in real time using a lightweight POST call
Detect and handle failure states early to offer users a retry path without friction
Avoid unnecessary data fetch calls by confirming job completion before calling /data
Simple request body — only the job_id is required

Use Cases

- Drive a real-time application status screen while the ITR analysis processes in the background - Trigger automated underwriting workflows the moment `completed` status is detected - Alert credit teams when an ITR job fails so they can request alternate income documents - Update in-app progress indicators during a self-employed borrower's loan application flow - Poll on the backend and push a notification to the user once their ITR data is ready - Handle `failed` status gracefully by surfacing a manual document upload fallback - Log all job status transitions with timestamps for end-to-end audit trails per loan application - Integrate status polling into LOS workflows to trigger next-step actions automatically - Monitor ITR job completion rates across your applicant base for operational analytics

Technical Implementation

All API requests require authentication using your Finpass API credentials passed as request headers.

Obtain API Credentials: Register with Finpass to receive your X-API-KEY and X-API-SECRET.
Include in Requests: Add both keys to every request as HTTP headers.

Header	Value
`X-API-KEY`	Your assigned API Key
`X-API-SECRET`	Your assigned API Secret

Base URL: https://api.finpass.ai

### Request Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`X-API-KEY`	Yes	Your Finpass API Key
`X-API-SECRET`	Yes	Your Finpass API Secret

Request Body

Parameter	Type	Required	Description
`job_id`	string	Yes	The `job_id` received from the `/itr-analyzer/analyze` response

Example Request

{
  "job_id": "itr_job_x9k2m4p7q1r8"
}

### Response Parameters

Parameter	Type	Description
`success`	boolean	Indicates whether the request was processed successfully
`message`	string	Human-readable status message
`data.job_id`	string	The analysis job identifier
`data.status`	string	Current job status. See status lifecycle below
`data.pan`	string	The PAN number associated with this job
`data.updated_at`	string	Timestamp of the last status update (ISO 8601)

Job Status Lifecycle

Status	Terminal	Description
`initiated`	No	Job created; ITR portal login is in progress
`processing`	No	Credentials verified; ITR data is being extracted and analysed
`completed`	✅ Yes	Analysis complete — call `/itr-analyzer/data` to retrieve full results
`failed`	✅ Yes	Job failed due to a portal error, invalid credentials, or no ITR data found

Polling Strategy

Poll every 5–10 seconds after initiating the analysis. ITR extraction and analysis typically completes within 30–90 seconds. Stop polling once the status reaches completed or failed. Set a client-side timeout of 3–5 minutes and surface a retry prompt if neither terminal state is reached within that window.
:::

Example Successful Response

{
  "success": true,
  "message": "Job status fetched successfully",
  "data": {
    "job_id": "itr_job_x9k2m4p7q1r8",
    "status": "completed",
    "pan": "ABCDE1234F",
    "updated_at": "2024-11-15T10:23:42Z"
  }
}

Possible Error Responses

```json { "success": false, "message": "No analysis job found for the provided job_id.", "error_code": "NOT_FOUND" } ``` Returned when the `job_id` does not match any active or past analysis job on record. ```json { "success": false, "message": "Unauthorized. Invalid or missing API credentials.", "error_code": "UNAUTHORIZED" } ``` Returned when `X-API-KEY` or `X-API-SECRET` is missing or invalid.

Integration Best Practices

- Store and handle the `job_id` on your backend only — never expose it in client-side code or public-facing URLs - Log all status transitions with timestamps against the loan application record for compliance and audit purposes - Rate-limit your polling to once every 5–10 seconds to avoid unnecessary API quota consumption - Treat the `failed` status as a signal to re-verify user credentials before retrying — do not retry blindly - Display an animated progress screen while polling, with an estimated wait time (e.g., "Fetching your ITR data — this usually takes under a minute") - For the `failed` status, show a friendly error with an actionable next step — offer a manual income document upload as a fallback - Avoid polling indefinitely — set a frontend timeout of 3–5 minutes and prompt users to retry the initiation if no terminal state is reached - Show a clear success confirmation once `completed` is detected before proceeding to underwriting or data display

Code Samples

```bash curl -X POST "https://api.finpass.ai/itr-analyzer/status" \ -H "Content-Type: application/json" \ -H "X-API-KEY: " \ -H "X-API-SECRET: " \ -d '{ "job_id": "itr_job_x9k2m4p7q1r8" }' ``` ```python import requests import time

url = "https://api.finpass.ai/itr-analyzer/status"

headers = {
"Content-Type": "application/json",
"X-API-KEY": "<your_api_key>",
"X-API-SECRET": "<your_api_secret>"
}

payload = {
"job_id": "itr_job_x9k2m4p7q1r8"
}

terminal_statuses = {"completed", "failed"}

while True:
response = requests.post(url, json=payload, headers=headers)
data = response.json()
status = data["data"]["status"]
print("Current status:", status)

if status in terminal_statuses:
print("Terminal status reached:", status)
break

time.sleep(5)

</Tab>
<Tab title="Node.js">
```javascript
const axios = require("axios");

const url = "https://api.finpass.ai/itr-analyzer/status";

const headers = {
  "Content-Type": "application/json",
  "X-API-KEY": "<your_api_key>",
  "X-API-SECRET": "<your_api_secret>"
};

const payload = { job_id: "itr_job_x9k2m4p7q1r8" };
const terminalStatuses = new Set(["completed", "failed"]);

const pollStatus = async () => {
  const response = await axios.post(url, payload, { headers });
  const { status } = response.data.data;
  console.log("Current status:", status);

  if (!terminalStatuses.has(status)) {
    setTimeout(pollStatus, 5000);
  } else {
    console.log("Terminal status reached:", status);
  }
};

pollStatus().catch(err => console.error("Error:", err.response?.data || err.message));

Related APIs

ITR Analyzer — Initiate Analysis — Start a new ITR analysis job using the user's IT portal credentials
ITR Analyzer — Get Full Data — Retrieve the complete structured ITR analysis once the job status is completed

Compliance and Legal Considerations

Job status data is associated with a user's income tax filing session initiated under their explicit consent. Ensure that job_id mappings are retained only for the duration required by your regulatory obligations and are not exposed to unauthorised personnel. Do not use job metadata to infer or store personal financial behaviour beyond what is needed for the declared income verification purpose. Access to this endpoint requires the ITR_ANALYZER permission on your Finpass account.