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

Submit 2FA OTP

POST
/api/v1/services/itr-analyzer/2fa/submit

Submit 2FA OTP#

Endpoint Overview
POST /api/v1/services/itr-analyzer/2fa/submit

Description#

The Submit 2FA OTP API completes the Income Tax Return (ITR) portal's two-factor authentication challenge by submitting the OTP entered by the taxpayer. On success, the upstream portal session is validated and the credentials become ready for ITR data retrieval.
This endpoint is the third step of the 2FA flow: after /2fa/generate dispatches the OTP, the taxpayer enters it in your UI, and your backend forwards it here. A successful response indicates the credentials are now usable for downstream ITR operations.
Key Benefits
Closes the 2FA Loop — Confirms the OTP and unlocks downstream ITR retrieval.
Deterministic Outcome — Returns clear success or failure so the UI can advance or re-prompt.
Single-Use Verification — OTP is validated server-side; clients never need to store it.
Quick Recovery on Failure — Failed submissions can be retried until the OTP expires.

Use Cases#

Lending & NBFC
Accounting & Audit
Wealth & Tax Tech
Complete borrower authentication within a single in-app loan application flow.
Validate periodic re-authentication for monitoring engagements without manual portal logins.
Move applications from "pending OTP" to "ready for ITR pull" in underwriting queues.

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 2FA is being completed.
otpstringYesThe one-time password received by the taxpayer on their registered contact.

Example Request#

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

Response Parameters#

ParameterTypeDescription
successbooleanIndicates whether the OTP was accepted by the ITR portal.
dataobjectContainer holding verification details.
data.client_idstringThe client identifier for which 2FA was completed.
data.statusstringVerification status. Typical value: verified.
data.messagestringHuman-readable confirmation of 2FA completion.

Example Successful Response#

{
  "success": true,
  "data": {
    "client_id": "CLIENT_ID",
    "status": "verified",
    "message": "2FA verification completed successfully."
  }
}

Possible Error Responses#

Invalid OTP
OTP Expired
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.
Use separate API credentials for sandbox and production environments.
User Experience Guidelines
Pre-fill OTPs received via SMS where the platform supports OTP autofill APIs (e.g., Android SMS Retriever).
Show specific feedback for INVALID_OTP vs OTP_EXPIRED so users can correct vs request a new OTP.
Display a visible attempt counter so users know how many tries remain before they must regenerate.
After repeated failures, offer a clear pathway to the password reset flow.
On success, smoothly transition users to the next step (e.g., "Fetching your ITR data...") without unnecessary screens.

Code Samples#

cURL
Python
Node.js
Related APIs
Generate 2FA OTP — Dispatches the OTP that this endpoint verifies.
Check Credentials Status — Run after a successful submission to confirm credentials are now valid.
Forget Password — Alternative recovery path when OTP-based 2FA cannot be completed.
Compliance and Legal Considerations
This endpoint processes OTPs, which are confidential authentication factors under India's Information Technology Act, 2000. Integrators must not log, store, cache, or otherwise persist OTP values at any layer of their stack. Submitted OTPs must be transmitted exclusively over TLS and discarded from memory immediately after the API call resolves. Integrators must also enforce reasonable attempt limits to discourage brute-force attacks consistent with industry security standards and obligations under 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/2fa/submit' \
--header 'x-api-key;' \
--header 'x-api-secret;' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "CLIENT_ID",
    "otp": "123456"
}'
Response Response Example
{}
Previous
Generate 2FA
Next
Initiate ITR Password Reset
Built with