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

Generate 2FA

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

Generate 2FA OTP#

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

Description#

The Generate 2FA OTP API triggers the Income Tax Return (ITR) portal's two-factor authentication challenge for a taxpayer identified by client_id. When the ITR portal mandates a 2FA step (typically an OTP sent to the registered mobile number or email), this endpoint instructs the upstream service to request that OTP from the portal so the end user can receive and submit it.
This endpoint is the second step of the 2FA flow: after the credential check returns 2fa_required, call this endpoint to dispatch the OTP, then submit the user-entered OTP through the /2fa/submit endpoint.
Key Benefits
Programmatic 2FA Trigger — Initiates portal OTP delivery without manual portal interaction.
Workflow Continuity — Bridges credential validation and ITR retrieval without requiring users to leave your app.
Clear State Transitions — Returns a deterministic acknowledgement so the UI can move to the OTP entry screen.
Compliance-Friendly — Preserves the portal's own 2FA controls instead of bypassing them.

Use Cases#

Lending & NBFC
Accounting & Audit
Wealth & Tax Tech
Re-authenticate borrowers periodically during long-running monitoring engagements.
Recover from 2fa_required status detected during pre-disbursement income re-verification.
Coordinate OTP entry within in-app loan application flows to keep users in-context.

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 portal account requires 2FA.

Example Request#

{
  "client_id": "CLIENT_ID"
}
3
Process Response

Response Parameters#

ParameterTypeDescription
successbooleanIndicates whether the OTP generation request was accepted by the ITR portal.
dataobjectContainer holding OTP dispatch details.
data.client_idstringThe client identifier for which the OTP was triggered.
data.statusstringOTP dispatch status. Typical value: otp_sent.
data.messagestringHuman-readable confirmation including delivery channel hints (e.g., "OTP sent to registered mobile").

Example Successful Response#

{
  "success": true,
  "data": {
    "client_id": "CLIENT_ID",
    "status": "otp_sent",
    "message": "OTP sent to registered contact on the ITR portal."
  }
}

Possible Error Responses#

2FA Not Required
Client Not Found
OTP Dispatch Failed
Unauthorized
{
  "success": false,
  "error": {
    "code": "TWOFA_NOT_REQUIRED",
    "message": "The ITR portal did not require a 2FA challenge for this client."
  }
}
Returned when 2FA generation is invoked but the portal does not currently require it. Proceed directly with the ITR retrieval flow.

Integration Best Practices#

Security Recommendations
Always invoke this endpoint over HTTPS and validate TLS certificates.
Treat X-API-Key and X-API-Secret as highly sensitive secrets; rotate them periodically.
Implement strict rate limits on your side to prevent OTP-flooding of the underlying taxpayer.
Log OTP dispatch events for audit, but never log the OTP value itself.
Use separate API credentials for sandbox and production environments.
User Experience Guidelines
Show a clear message explaining that an OTP has been sent to the taxpayer's registered contact on the ITR portal.
Surface a countdown and a resend control with a sensible cool-down (e.g., 30–60 seconds) before allowing regeneration.
Pre-focus the OTP entry field as soon as this endpoint succeeds to reduce friction.
Provide a fallback link to the password reset flow if the user reports they cannot receive the OTP.
Avoid silent retries; OTP dispatch failures should be surfaced to the user with actionable guidance.

Code Samples#

cURL
Python
Node.js
Related APIs
Check Credentials Status — Run before this endpoint to confirm whether 2FA is actually required.
Submit 2FA OTP — Consumes the OTP entered by the taxpayer to complete the 2FA challenge.
ITR Login Create Client — Registers credentials and returns the client_id referenced here.
Compliance and Legal Considerations
This endpoint triggers OTP dispatch by the ITR portal to the taxpayer's registered contact details. Misuse — for example, repeatedly triggering OTPs without the taxpayer's intent — could constitute harassment or unauthorized access under India's Information Technology Act, 2000. Integrators must enforce intent checks and rate limits on their side, obtain documented user consent before invoking this endpoint, and provide users with a way to revoke that consent. Logging must not retain the OTP value, only the dispatch event metadata.

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/generate' \
--header 'x-api-key;' \
--header 'x-api-secret;' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "CLIENT_ID"
}'
Response Response Example
{}
Previous
Check Credential
Next
Submit 2FA OTP
Built with