ITR Generate 2FA OTP

Endpoint Overview

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

Description

The ITR Generate 2FA API initiates two-factor authentication by sending a One-Time Password (OTP) to the user associated with an existing Income Tax Return (ITR) verification session. This endpoint is a critical step in the ITR verification workflow, ensuring that only authorized individuals can access sensitive tax filing data by triggering an OTP delivery to the registered mobile number or email linked to the taxpayer's account.

This API acts as the second step in the ITR data retrieval process. After initiating an ITR verification session (which returns a client_id), you must call this endpoint to generate and send an OTP for identity confirmation. The OTP must then be submitted via the corresponding OTP verification endpoint to unlock access to the taxpayer's ITR data. This two-factor mechanism ensures compliance with data protection requirements and prevents unauthorized access to confidential financial records.

Key Benefits

Secure Tax Data Access: Adds a robust second layer of authentication before exposing sensitive ITR data, protecting taxpayer privacy

Seamless Workflow Integration: Designed to fit naturally into multi-step ITR verification flows with a simple single-parameter request

Real-Time OTP Delivery: Instantly sends OTP to the taxpayer's registered contact, minimizing wait times during verification

Regulatory Compliance: Ensures adherence to income tax authority guidelines requiring explicit taxpayer consent via OTP before data retrieval

Use Cases

Lending & Credit

Financial Services

HR & Employment

Trigger OTP for borrower consent during income verification for personal loan, home loan, or credit card applications

Initiate 2FA as part of automated underwriting pipelines to securely fetch ITR data for creditworthiness assessment

Enable real-time income proof collection during digital lending journeys without manual document uploads

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication. Format: `Bearer <JWT_TOKEN>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
client_id	string	Yes	Unique client identifier obtained from the initial ITR verification session. This ID links the OTP generation request to the specific taxpayer session. Format example: `itr_GphpGlzxZOficAventBk`

Example Request

{
  "client_id": "itr_GphpGlzxZOficAventBk"
}

Important Notes:

The client_id must be obtained from a prior ITR session initiation API call

Each client_id is tied to a specific taxpayer session and cannot be reused across different verification requests

The client_id has a limited validity window; ensure the 2FA request is made promptly after session creation

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the OTP generation result
data.otp_sent	boolean	Indicates whether the OTP was successfully sent to the taxpayer's registered contact. `true` confirms delivery was initiated.
status_code	integer	HTTP status code of the response (200 for success)
message_code	string	Machine-readable code for the result status (e.g., "success")
message	string	Human-readable message describing the result (e.g., "OTP Sent")
success	boolean	Indicates if the API request was processed successfully

Example Successful Response

{
  "data": {
    "otp_sent": true
  },
  "status_code": 200,
  "message_code": "success",
  "message": "OTP Sent",
  "success": true
}

Response Notes:

A success: true response with otp_sent: true confirms that the OTP has been dispatched to the taxpayer's registered mobile number or email

The OTP has a limited validity period; ensure the user submits it promptly via the OTP verification endpoint

If the OTP is not received, the user can retry by calling this endpoint again with the same client_id

Possible Error Responses

Invalid Client ID

Authentication Error

Rate Limit / OTP Retry Exceeded

Server Error

{
    "data": null,
    "status_code": 404,
    "message_code": null,
    "message": "Client with given Client ID not found.",
    "success": false
}

This error occurs when the provided client_id is incorrect, does not exist, or the associated session has expired. Initiate a new ITR verification session to obtain a fresh client_id.

Integration Best Practices

Security Recommendations

Secure Client ID Handling: Treat the client_id as a sensitive session token; do not expose it in client-side code, URLs, or logs

Token Management: Store JWT tokens securely on the server side and implement automatic token refresh mechanisms to handle expiration

HTTPS Only: Always use HTTPS endpoints to encrypt request and response data containing session identifiers

OTP Retry Controls: Implement server-side controls to limit OTP regeneration attempts per session, preventing abuse and potential account lockout

Session Timeout: Enforce timeout logic on the client_id session to discard stale verification attempts and reduce attack surface

User Experience Guidelines

Clear OTP Instructions: Inform users that an OTP will be sent to their registered mobile/email before triggering the request, so they are prepared to receive it

Loading Indicators: Display a processing spinner or status message while the OTP generation request is in progress

Resend Mechanism: Provide a clearly visible "Resend OTP" option with a cooldown timer (e.g., 30 seconds) to prevent accidental multiple triggers

Error Messaging: Display user-friendly error messages when OTP generation fails, with actionable guidance (e.g., "Session expired. Please restart the verification process.")

OTP Input Prompt: Immediately present an OTP input field upon successful response, guiding the user to the next step seamlessly

Timeout Awareness: Inform users about the OTP validity duration and prompt them to enter it before expiry

Code Samples

cURL

Python

Node.js

Related APIs

ITR Session Initiation API: Initiates the ITR verification session and returns the client_id required by this endpoint. Must be called before generating 2FA OTP.

ITR OTP Verification API: Accepts the OTP entered by the taxpayer to complete two-factor authentication and unlock access to ITR data.

ITR Data Fetch API: Retrieves the complete ITR filing data after successful OTP verification, including income details, tax computation, and filing status.

Compliance and Legal Considerations

This API facilitates access to sensitive taxpayer income and financial data protected under the Income Tax Act and applicable data privacy regulations. Ensure explicit taxpayer consent is obtained before initiating the verification process. The OTP mechanism serves as the taxpayer's digital consent for data retrieval — do not bypass or simulate this step. All retrieved ITR data must be handled in accordance with applicable data protection laws, including the Digital Personal Data Protection Act (DPDPA), GDPR (if applicable), and sector-specific regulations. Implement strict access controls, data encryption at rest and in transit, and well-defined data retention and deletion policies for any ITR information obtained through this workflow. Maintain audit trails of all 2FA initiation and verification events for regulatory compliance and dispute resolution.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/itr/generate-2fa' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "itr_GphpplzxZOficAventBk" }'

Generate 2FA

ITR Generate 2FA OTP#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses