ITR Analyzer — Get Full Data

Endpoint Overview

POST /api/v1/itr-analyzer/data

Description

The ITR Analyzer Get Full Data API returns the complete, structured output of an ITR analysis job — including multi-year income details, tax computation, gross total income breakdown, deductions, refund status, and financial health signals derived directly from the Income Tax Department's e-filing portal.

This endpoint is available only after the job status reaches completed. The data returned here is the primary input for income verification, credit underwriting, and financial assessment workflows for self-employed and salaried individuals.

Key Benefits

Retrieve multi-year ITR data in a single, clean structured JSON — no PDF parsing required

Access declared gross income, net taxable income, and tax paid across multiple assessment years

Use income trend data to assess consistency and growth for high-ticket credit underwriting

Get refund and demand status signals that indicate the taxpayer's compliance posture

Use Cases

Banking & Lending

Fintech & Payments

Enterprise & Compliance

Verify self-employed income across 2–3 assessment years for business and personal loan underwriting

Cross-check declared income against bank statement salary credits for salaried applicants

Assess income growth trajectory as a forward-looking creditworthiness signal

Technical Implementation

Authentication

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 Parameters

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"
}

Process Response

Response Parameters

Top-Level

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.pan`	string	The PAN number for which ITR data was fetched
`data.name`	string	Full name of the taxpayer as registered on the IT portal
`data.filing_status`	string	Overall filing status (e.g., `Regular`, `Revised`, `Belated`)
`data.itr_records`	array	List of ITR filings across assessment years

`data.itr_records[]` — Per Assessment Year ITR Data

Parameter	Type	Description
`assessment_year`	string	Assessment year of the filing (e.g., `2024-25`)
`itr_type`	string	ITR form type filed (e.g., `ITR-1`, `ITR-2`, `ITR-3`, `ITR-4`)
`filing_date`	string	Date on which the ITR was filed (YYYY-MM-DD)
`acknowledgement_number`	string	Unique ITR acknowledgement number from the IT portal
`gross_total_income`	number	Gross total income before deductions (in INR)
`total_deductions`	number	Total deductions claimed under Chapter VI-A (in INR)
`net_taxable_income`	number	Net taxable income after all deductions (in INR)
`tax_payable`	number	Total tax payable as computed in the return (in INR)
`tds_amount`	number	Total TDS deducted at source (in INR)
`advance_tax_paid`	number	Advance tax paid during the financial year (in INR)
`self_assessment_tax`	number	Self-assessment tax paid at the time of filing (in INR)
`refund_amount`	number	Refund due to the taxpayer, if any (in INR); `0` if no refund
`demand_amount`	number	Outstanding tax demand raised by the IT department, if any (in INR); `0` if none
`refund_status`	string	Current refund status (e.g., `Issued`, `Pending`, `Not Applicable`)
`income_heads.salary`	number	Income from salary (in INR)
`income_heads.house_property`	number	Income or loss from house property (in INR)
`income_heads.business_profession`	number	Income from business or profession (in INR)
`income_heads.capital_gains`	number	Income from capital gains (in INR)
`income_heads.other_sources`	number	Income from other sources (in INR)

Example Successful Response

{
  "success": true,
  "message": "ITR data fetched successfully",
  "data": {
    "job_id": "itr_job_x9k2m4p7q1r8",
    "pan": "ABCDE1234F",
    "name": "RAHUL SHARMA",
    "filing_status": "Regular",
    "itr_records": [
      {
        "assessment_year": "2024-25",
        "itr_type": "ITR-1",
        "filing_date": "2024-07-15",
        "acknowledgement_number": "123456789012345",
        "gross_total_income": 1080000,
        "total_deductions": 150000,
        "net_taxable_income": 930000,
        "tax_payable": 93600,
        "tds_amount": 88000,
        "advance_tax_paid": 0,
        "self_assessment_tax": 5600,
        "refund_amount": 0,
        "demand_amount": 0,
        "refund_status": "Not Applicable",
        "income_heads": {
          "salary": 1020000,
          "house_property": -40000,
          "business_profession": 0,
          "capital_gains": 0,
          "other_sources": 100000
        }
      },
      {
        "assessment_year": "2023-24",
        "itr_type": "ITR-1",
        "filing_date": "2023-07-28",
        "acknowledgement_number": "987654321098765",
        "gross_total_income": 984000,
        "total_deductions": 150000,
        "net_taxable_income": 834000,
        "tax_payable": 78200,
        "tds_amount": 81500,
        "advance_tax_paid": 0,
        "self_assessment_tax": 0,
        "refund_amount": 3300,
        "demand_amount": 0,
        "refund_status": "Issued",
        "income_heads": {
          "salary": 960000,
          "house_property": 0,
          "business_profession": 0,
          "capital_gains": 0,
          "other_sources": 24000
        }
      },
      {
        "assessment_year": "2022-23",
        "itr_type": "ITR-1",
        "filing_date": "2022-07-20",
        "acknowledgement_number": "543216789054321",
        "gross_total_income": 840000,
        "total_deductions": 150000,
        "net_taxable_income": 690000,
        "tax_payable": 55500,
        "tds_amount": 57000,
        "advance_tax_paid": 0,
        "self_assessment_tax": 0,
        "refund_amount": 1500,
        "demand_amount": 0,
        "refund_status": "Issued",
        "income_heads": {
          "salary": 840000,
          "house_property": 0,
          "business_profession": 0,
          "capital_gains": 0,
          "other_sources": 0
        }
      }
    ]
  }
}

Possible Error Responses

Job Not Complete

Invalid Job ID

Job Failed

Unauthorized

{
  "success": false,
  "message": "ITR data is not yet available. Job status is 'processing'. Please poll /itr-analyzer/status until status is 'completed'.",
  "error_code": "JOB_INCOMPLETE"
}

Returned when this endpoint is called before the analysis job reaches completed.

Integration Best Practices

Security Recommendations

Call this endpoint exclusively from your secure backend — never return raw ITR data to a frontend client

Encrypt ITR data at rest if storing it, as it constitutes highly sensitive personal financial and tax information

Apply field-level access controls so only authorised underwriting or compliance personnel can view ITR records

Purge ITR data once the loan application lifecycle is complete and beyond any mandatory retention period

User Experience Guidelines

Always verify job status via /itr-analyzer/status before calling this endpoint to avoid JOB_INCOMPLETE errors

Display a summarised income view (e.g., year-wise net taxable income trend) to underwriters before surfacing full details

Highlight demand_amount > 0 as a flag in your underwriting dashboard — outstanding tax demands may indicate compliance risk

Use income_heads.salary vs income_heads.business_profession to determine whether to apply salaried or self-employed underwriting criteria

Code Samples

cURL

Python

Node.js

Related APIs

ITR Analyzer — Initiate Analysis — Start a new ITR analysis job using the user's IT portal credentials

ITR Analyzer — Poll Status — Check the current processing state of an initiated ITR analysis job

Compliance and Legal Considerations

ITR data returned by this endpoint was accessed on behalf of the user from the Income Tax Department's e-filing portal under their explicit consent. This data constitutes sensitive personal financial information and must only be used for the declared purpose — such as credit underwriting or income verification. Do not share, sell, or repurpose ITR data with unauthorised third parties. Retain ITR records only for the mandatory period required by your regulatory framework and implement data deletion policies accordingly. Automated credit decisions based on ITR data must comply with RBI's Fair Practices Code and applicable consumer protection regulations. Access to this endpoint requires the ITR_ANALYZER permission on your Finpass account.

ITR Analyzer — Get Full Data

ITR Analyzer — Get Full Data#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Top-Level#

data.itr_records[] — Per Assessment Year ITR Data#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

ITR Analyzer — Get Full Data

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Top-Level

`data.itr_records[]` — Per Assessment Year ITR Data

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples