Finpass API Collection
  1. ITR Analyzer
  • Introduction
  • Bureau
    • Commercial Credit Report
      POST
    • Multi-Bureau Fetch
      POST
  • Bank Statement Analyser
    • Batch Upload Statements
      POST
    • Batch Result
      GET
    • Upload Statement
      POST
    • Statement Result
      GET
  • Account Aggregator
    • Initialize
      POST
    • Fetch JSON Report
      POST
    • Fetch PDF Report
      POST
    • Refresh Data
      POST
  • Corporate
    • CIN Lookup
      POST
    • LLPIN
      POST
    • PAN Lookup
      POST
    • Company Autocomplete
      POST
  • EPFO
    • Fetch EPFO Data by Mobile Number
      POST
    • EPFO-CRIF Combined Report
      POST
  • ITR Analyzer
    • Initialize
      POST
    • Status
      POST
    • ITR Analyzer — Get Full Data
      POST
    • Create ITR Login Client
      POST
    • Check Credential
      POST
    • Generate 2FA
      POST
    • Submit 2FA OTP
      POST
    • Initiate ITR Password Reset
      POST
    • Confirm Password Reset (Submit OTP)
      POST
  • AA-BSA Analyzer
    • Initialize
    • Status
    • AA BSA — Statement Result
    • AA BSA — Analysis JSON
  • GST Analyser
    • Analyze
    • Status
    • GST Data
  • Hosted Collection
    • Create ITR Collection Session
    • Create GST Collection Session
  1. ITR Analyzer

Initiate ITR Password Reset

POST
/api/v1/services/itr-analyzer/forget-password

Initiate ITR Password Reset#

Endpoint Overview
POST /api/v1/services/itr-analyzer/forget-password

Description#

The Initiate ITR Password Reset API begins the password reset flow on the Income Tax Return (ITR) portal for a taxpayer identified by client_id. The endpoint accepts the desired new password and instructs the upstream service to dispatch an OTP to the taxpayer's registered contact for confirmation. The new password is held in pending state until the OTP is verified via /forget-password/submit-otp.
Use this endpoint when:
The credential check returns password_reset_required.
The taxpayer reports they cannot log in despite confirming their PAN.
You need to rotate a previously stored password that has expired.
Key Benefits
In-Flow Recovery — Resets credentials without forcing users to navigate the ITR portal directly.
Secure Pending State — The new password is staged but not activated until OTP verification.
Workflow Continuity — Keeps the taxpayer within your application throughout the reset journey.
Compliance-Friendly — Honors the ITR portal's own OTP-based confirmation flow.

Use Cases#

Lending & NBFC
Accounting & Audit
Wealth & Tax Tech
Recover stalled income verifications when stored borrower passwords are no longer valid.
Offer a frictionless "Forgot ITR password?" path within loan application screens.
Reduce manual operations overhead by handling resets programmatically.

Technical Implementation#

1
Authentication
All API requests require authentication using API key headers. Authentication follows these steps:
1.
Obtain API Credentials: Register with Finpass to receive your X-API-Key and X-API-Secret.
2.
Include in Requests: Add both headers to every request — X-API-Key: <your_key> and X-API-Secret: <your_secret>.
3.
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.
2
Request Parameters

Request Headers#

HeaderRequiredDescription
X-API-KeyYesYour Finpass-issued API key.
X-API-SecretYesYour Finpass-issued API secret paired with the key.
Content-TypeYesMust be set to application/json.

Request Body#

ParameterTypeRequiredDescription
client_idstringYesThe client identifier for the taxpayer whose ITR password is being reset.
passwordstringYesThe desired new ITR portal password. Transmitted only in-transit over TLS and held in pending state until OTP confirmation.

Example Request#

{
  "client_id": "CLIENT_ID",
  "password": "new_password"
}
3
Process Response

Response Parameters#

ParameterTypeDescription
successbooleanIndicates whether the reset request was accepted and OTP dispatch initiated.
dataobjectContainer holding reset flow state.
data.client_idstringThe client identifier for which the reset was initiated.
data.statusstringReset flow status. Typical value: otp_sent.
data.messagestringHuman-readable confirmation including delivery channel hints.

Example Successful Response#

{
  "success": true,
  "data": {
    "client_id": "CLIENT_ID",
    "status": "otp_sent",
    "message": "OTP dispatched to the taxpayer's registered contact for password reset confirmation."
  }
}

Possible Error Responses#

Weak Password
Client Not Found
OTP Dispatch Failed
Unauthorized
{
  "success": false,
  "error": {
    "code": "WEAK_PASSWORD",
    "message": "The new password does not meet the ITR portal's complexity requirements."
  }
}
Returned when the proposed password fails the ITR portal's complexity rules. Prompt the user to choose a stronger password.

Integration Best Practices#

Security Recommendations
Never log, persist, or cache the password field on your servers — pass it through to the API in-memory only.
Always invoke this endpoint over HTTPS and validate TLS certificates.
Enforce password complexity rules on the client side that align with the ITR portal's requirements to reduce failed attempts.
Rate-limit reset initiations per client_id to prevent abuse and accidental account lockouts.
Use separate API credentials for sandbox and production environments.
User Experience Guidelines
Display password strength meters and explicit complexity requirements before submission.
Clearly explain that an OTP will be sent to the taxpayer's registered contact on the ITR portal.
Provide a single "Resend OTP" control with a sensible cool-down rather than allowing rapid reattempts.
Warn users that the new password will only become active after OTP verification.
Offer a clear escape hatch (e.g., "Use a different account") if the user cannot complete the reset.

Code Samples#

cURL
Python
Node.js
Related APIs
Forget Password Submit OTP — Confirms the OTP and activates the new password staged by this endpoint.
Check Credentials Status — Surfaces password_reset_required triggering the need to call this endpoint.
ITR Login Create Client — Bootstraps the client_id consumed by this endpoint.
Compliance and Legal Considerations
This endpoint stages a new ITR portal password against the taxpayer's account. Integrators must collect explicit, informed consent before initiating a password reset on behalf of a taxpayer, and must not retain the proposed password on their own infrastructure. Misuse — for example, attempting to reset another individual's ITR password without authorization — would constitute unauthorized access under India's Information Technology Act, 2000. Maintain an auditable trail of consent and reset initiations, and provide taxpayers with timely notifications of any reset activity carried out on their behalf in line with the Digital Personal Data Protection Act, 2023 (DPDP Act).

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200Success
application/json
Bodyapplication/json

Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.finpass.ai/api/v1/services/itr-analyzer/forget-password' \
--header 'x-api-key;' \
--header 'x-api-secret;' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "CLIENT_ID",
    "password": "new_password"
}'
Response Response Example
{}
Previous
Submit 2FA OTP
Next
Confirm Password Reset (Submit OTP)
Built with