Finpass API Collection
  1. ITR Analyzer
  • Introduction
  • Bank Statement Analyser
    • Upload Statement
      POST
    • Statement Result
      GET
  • Account Aggregator
    • Initialize
      POST
    • Fetch JSON Report
      POST
    • Fetch PDF Report
      POST
    • Refresh Data
      POST
  • Multi Bureau
    • Multi-Bureau Fetch
      POST
  • Corporate
    • CIN Lookup
      POST
    • LLPIN
      POST
    • PAN Lookup
      POST
    • Company Autocomplete
      POST
  • EPFO
    • EPFO-CRIF Combined Report
      POST
  • ITR Analyzer
    • Initialize
      POST
    • Status
      GET
    • ITR Analyzer — Get Full Data
      GET
  • AA-BSA Analyzer
    • Initialize
      POST
    • Status
      GET
    • AA BSA — Statement Result
      GET
    • AA BSA — Analysis JSON
      GET
  1. ITR Analyzer

Initialize

POST
/api/v1/itr-analyzer/analyze

ITR Analyzer — Initiate Analysis#

Endpoint Overview
POST /api/v1/itr-analyzer/analyze

Description#

The ITR Analyzer Initiate Analysis API triggers an automated fetch and analysis of an individual's Income Tax Return (ITR) data directly from the Income Tax Department's e-filing portal using their PAN and portal credentials. It submits the job asynchronously and returns a job_id to track analysis progress in subsequent calls.
This is always the first call in the ITR Analyzer workflow. All downstream steps — polling job status and retrieving the full analysed data — depend on the job_id returned here.
Key Benefits
Fetch ITR data directly from the IT e-filing portal — no manual document uploads required
Retrieve multi-year ITR history in a single job submission for comprehensive income assessment
Eliminate OCR errors and document tampering risks associated with PDF-based ITR verification
Fully automated — analysis runs asynchronously with no manual intervention needed

Use Cases#

Banking & Lending
Fintech & Payments
Enterprise & Compliance
Verify declared income against ITR filings during personal loan, home loan, or LAP underwriting
Assess self-employed and business owner income using multi-year ITR trends
Cross-check ITR gross total income against bank statement credits for fraud detection

Technical Implementation#

1
Authentication
All API requests require authentication using your Finpass API credentials passed as request headers.
1.
Obtain API Credentials: Register with Finpass to receive your X-API-KEY and X-API-SECRET.
2.
Include in Requests: Add both keys to every request as HTTP headers.
HeaderValue
X-API-KEYYour assigned API Key
X-API-SECRETYour assigned API Secret
Base URL: https://api.finpass.ai
2
Request Parameters

Request Headers#

HeaderRequiredDescription
Content-TypeYesMust be application/json
X-API-KEYYesYour Finpass API Key
X-API-SECRETYesYour Finpass API Secret

Request Body#

ParameterTypeRequiredDescription
usernamestringYesThe individual's PAN used to log in to the IT e-filing portal (e.g., ABCDE1234F). Input is case-insensitive and will be automatically uppercased.
passwordstringYesThe individual's IT e-filing portal password. Handled securely and never stored post-session.

Example Request#

{
  "username": "ABCDE1234F",
  "password": "your_itr_portal_password"
}
3
Process Response

Response Parameters#

ParameterTypeDescription
successbooleanIndicates whether the analysis job was submitted successfully
messagestringHuman-readable status message
data.job_idstringUnique identifier for this analysis job — use this in all subsequent API calls
data.statusstringCurrent job status — will be initiated at this stage
data.panstringPAN associated with this job, masked for security
data.created_atstringTimestamp when the job was created (ISO 8601)

Example Successful Response#

{
  "success": true,
  "message": "ITR analysis job submitted successfully",
  "data": {
    "job_id": "itr_job_x9y8z7w6v5u4",
    "status": "initiated",
    "pan": "ABCDE****F",
    "created_at": "2024-11-15T10:22:00Z"
  }
}

Possible Error Responses#

Invalid PAN Format
Invalid Credentials
Portal Unavailable
Unauthorized
{
  "success": false,
  "message": "Invalid PAN format. PAN must be a 10-character alphanumeric string (e.g., ABCDE1234F).",
  "error_code": "INVALID_INPUT"
}
Returned when the provided username does not conform to the standard 10-character PAN format.

Integration Best Practices#

Security Recommendations
Never log or store the password field on your servers — treat it as a transient, in-memory value for the duration of the API call
Collect IT portal credentials from the user in a secure, encrypted form field and transmit only over HTTPS
Store the job_id securely on your backend and never expose it in client-side code or browser URLs
Obtain explicit written consent from the user before submitting their IT portal credentials to this API
User Experience Guidelines
Clearly inform the user that their IT e-filing portal credentials are being used solely to fetch their ITR data and will not be stored
Display a confirmation step before submitting credentials, allowing the user to review and approve the data access
Show a loading state immediately after submission — the analysis runs asynchronously and may take 30–60 seconds
If INVALID_CREDENTIALS is returned, prompt the user to verify their IT portal login before retrying

Code Samples#

cURL
Python
Node.js
Related APIs
ITR Analyzer — Poll Status — Check the processing status of a submitted ITR analysis job
ITR Analyzer — Get Full Data — Retrieve the complete ITR analysis results once the job is complete
Compliance and Legal Considerations
This API accesses the Income Tax Department's e-filing portal on behalf of the user using their credentials. You must obtain explicit, informed consent from the individual before initiating this API call, clearly stating the purpose of data access. Credential handling must comply with applicable data protection laws including the Digital Personal Data Protection Act (DPDP), 2023. ITR data retrieved must only be used for the declared purpose — such as income verification or credit underwriting — and must not be shared with unauthorised third parties or retained beyond the period required by your regulatory framework. Access to this endpoint requires the ITR_ANALYZER permission on your Finpass account.

Request

Body Params application/jsonRequired

Examples

Responses

🟢200Success
application/json
Body

Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.finpass.ai/api/v1/itr-analyzer/analyze' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "ABCDE1234F",
    "password": "your_itr_portal_password"
}'
Response Response Example
{
    "doc_id": "itr_analyzer_69d4e95e_01882b27d376ca214b3561e",
    "job_id": "itr_f2aecbf3-4b37-4d76-b779-7f314a15122d",
    "status": "pending"
}
Previous
EPFO-CRIF Combined Report
Next
Status
Built with