Create ITR Login Client

Endpoint Overview

POST /api/v1/services/itr-analyzer/itr-login/create-client

Description

The Create ITR Login Client API registers a new taxpayer credential set against the ITR Analyzer service. The endpoint accepts the taxpayer's PAN (as username) and current ITR portal password, validates them upstream, and returns a client_id that anchors all subsequent operations — credential checks, 2FA flows, password resets, and ITR data retrieval.

This is the bootstrap step of any ITR Analyzer workflow. The returned client_id is the canonical reference used by every other endpoint in the service.

Key Benefits

Single Client Identifier — One client_id powers credential checks, 2FA, password resets, and data fetches.

Upstream Validation — Credentials are validated at registration time rather than at first use.

Workflow Anchor — Decouples sensitive credentials from downstream calls — only the client_id flows through your systems.

Reusable Across Sessions — Persist the client_id to power recurring ITR refreshes without re-collecting credentials.

Use Cases

Lending & NBFC

Accounting & Audit

Wealth & Tax Tech

Onboard borrowers by capturing their ITR credentials once and reusing the client_id for periodic income verification.

Support relationship managers in registering credentials on behalf of high-touch clients.

Decouple credential capture from underwriting workflows so analysts work only with client_ids.

Technical Implementation

Authentication

All API requests require authentication using API key headers. Authentication follows these steps:

Obtain API Credentials: Register with Finpass to receive your X-API-Key and X-API-Secret.

Include in Requests: Add both headers to every request — X-API-Key: <your_key> and X-API-Secret: <your_secret>.

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.

Request Parameters

Request Headers

Header	Required	Description
`X-API-Key`	Yes	Your Finpass-issued API key.
`X-API-Secret`	Yes	Your Finpass-issued API secret paired with the key.
`Content-Type`	Yes	Must be set to `application/json`.

Request Body

Parameter	Type	Required	Description
`username`	string	Yes	The taxpayer's PAN, which serves as the ITR portal username.
`password`	string	Yes	The taxpayer's current ITR portal password. Transmitted only in-transit over TLS.

Example Request

{
  "username": "PANNUMBER",
  "password": "current_password"
}

Process Response

Response Parameters

Parameter	Type	Description
`success`	boolean	Indicates whether the client was created successfully.
`data`	object	Container holding the new client identity.
`data.client_id`	string	The unique client identifier to be used in all subsequent ITR Analyzer calls.
`data.status`	string	Initial state of the client. Typical values: `active`, `2fa_required`, `password_reset_required`.
`data.message`	string	Human-readable confirmation or instruction.

Example Successful Response

{
  "success": true,
  "data": {
    "client_id": "CLIENT_ID",
    "status": "active",
    "message": "Client created successfully."
  }
}

Possible Error Responses

Invalid Credentials

Client Already Exists

Unauthorized

Validation Error

{
  "success": false,
  "error": {
    "code": "INVALID_ITR_CREDENTIALS",
    "message": "The provided PAN or password is incorrect."
  }
}

Returned when the supplied PAN/password fails authentication against the ITR portal. Verify with the taxpayer and retry.

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.

Treat the returned client_id as sensitive; restrict its exposure to trusted server-to-server contexts.

Store the client_id against your user record so future flows do not need to re-collect credentials.

Use separate API credentials for sandbox and production environments.

User Experience Guidelines

Display a clear consent screen explaining that ITR portal credentials will be used to fetch tax data on the taxpayer's behalf.

Validate the PAN format on the client side before submission to catch typos early.

Provide a "show password" toggle but never persist the entered password in browser storage.

If the response indicates 2fa_required or password_reset_required, route the user into the appropriate sub-flow immediately.

Use loading states and clear error messages to set expectations during the upstream validation step.

Code Samples

cURL

Python

Node.js

Related APIs

Check Credentials Status — Run after client creation to confirm credential health and detect 2FA or reset needs.

Generate 2FA OTP — Triggered when client creation indicates that 2FA is required.

Forget Password — Initiates the reset flow when credentials need rotation.

Compliance and Legal Considerations

This endpoint collects the taxpayer's PAN and ITR portal password — both highly sensitive identifiers under India's Income Tax Act, 1961, the Information Technology Act, 2000, and the Digital Personal Data Protection Act, 2023 (DPDP Act). Integrators must obtain explicit, informed, and revocable consent from the taxpayer before invoking this endpoint, must not persist the plaintext password on their own systems, and must clearly disclose the purposes for which ITR data will be fetched and used. Maintain a documented data retention and deletion policy aligned with applicable regulations and the taxpayer's rights.

Create ITR Login Client#

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