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

Confirm Password Reset (Submit OTP)

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

Confirm Password Reset (Submit OTP)#

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

Description#

The Confirm Password Reset API completes the ITR portal password reset flow by submitting the OTP received by the taxpayer to verify and activate the new password staged through /forget-password. On success, the previously staged password becomes the taxpayer's active ITR portal password and the credentials are ready for downstream operations.
This is the final step of the password reset flow: initiate reset (stages new password and triggers OTP) → submit OTP (activates new password). Until this endpoint is called successfully, the old password remains in effect.
Key Benefits
Closes the Reset Loop — Activates the new password and clears password_reset_required state.
Deterministic Outcome — Returns success or a specific failure code so the UI can advance or re-prompt.
Single-Use Verification — OTP is verified server-side; clients never need to store it.
Quick Recovery on Failure — Failed attempts can be retried until the OTP expires.

Use Cases#

Lending & NBFC
Accounting & Audit
Wealth & Tax Tech
Activate refreshed borrower credentials so income re-verification can resume immediately.
Unblock loan applications paused on stale ITR passwords.
Capture audit-grade timestamps of credential rotations for compliance reviews.

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 password reset is being confirmed.
otpstringYesThe one-time password received by the taxpayer on their registered ITR portal contact.

Example Request#

{
  "client_id": "CLIENT_ID",
  "otp": "123456"
}
3
Process Response

Response Parameters#

ParameterTypeDescription
successbooleanIndicates whether the OTP was accepted and the new password activated.
dataobjectContainer holding the reset completion details.
data.client_idstringThe client identifier whose password was reset.
data.statusstringReset completion status. Typical value: password_reset_success.
data.messagestringHuman-readable confirmation of password rotation.

Example Successful Response#

{
  "success": true,
  "data": {
    "client_id": "CLIENT_ID",
    "status": "password_reset_success",
    "message": "Password reset confirmed. New password is now active."
  }
}

Possible Error Responses#

Invalid OTP
OTP Expired
No Reset Pending
Client Not Found
Unauthorized
{
  "success": false,
  "error": {
    "code": "INVALID_OTP",
    "message": "The OTP entered is incorrect."
  }
}
Returned when the submitted OTP does not match the value dispatched by the ITR portal. Allow the user to retry.

Integration Best Practices#

Security Recommendations
Always invoke this endpoint over HTTPS and validate TLS certificates.
Treat the otp value as a short-lived secret; transmit only over TLS and never log or persist it.
Treat X-API-Key and X-API-Secret as highly sensitive secrets; rotate them periodically.
Implement attempt limits and lockouts on your side to mitigate brute-force OTP attacks during reset confirmation.
Use separate API credentials for sandbox and production environments.
User Experience Guidelines
Pre-fill OTPs received via SMS where platform autofill APIs are available.
Differentiate UI feedback for INVALID_OTP (retry) vs OTP_EXPIRED (restart flow).
Surface a clear success state confirming that the new password is now active and that downstream operations can resume.
After repeated failed attempts, offer a clean path to restart the password reset flow.
Send the taxpayer an in-app or email notification on successful reset for transparency and security.

Code Samples#

cURL
Python
Node.js
Related APIs
Forget Password (Initiate) — Stages the new password and triggers the OTP that this endpoint verifies.
Check Credentials Status — Run after a successful reset to confirm credentials are now valid.
Generate 2FA OTP — Used for the separate 2FA challenge flow, distinct from password reset.
Compliance and Legal Considerations
This endpoint completes a credential rotation on behalf of the taxpayer. OTP values processed by this endpoint must not be logged, stored, cached, or otherwise persisted at any layer of the integrator's stack. Successful resets should generate taxpayer-facing notifications consistent with best practices and the Digital Personal Data Protection Act, 2023 (DPDP Act), and integrators must retain audit trails of consent and reset events — without sensitive material — sufficient to demonstrate authorized use. Unauthorized credential rotation would constitute a violation under the Information Technology Act, 2000.

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/submit-otp' \
--header 'x-api-key;' \
--header 'x-api-secret;' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "CLIENT_ID",
    "otp": "123456"
}'
Response Response Example
{}
Previous
Initiate ITR Password Reset
Next
Initialize
Built with