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

Check Credential

POST
/api/v1/services/itr-analyzer/check-credentials

Check ITR Credentials Status#

Endpoint Overview
POST /api/v1/services/itr-analyzer/check-credentials

Description#

The Check ITR Credentials Status API verifies the validity and current state of a taxpayer's Income Tax Return (ITR) portal credentials previously registered against a client_id. The endpoint returns whether the stored credentials are usable for fetching ITR data, whether they have expired, whether the portal requires 2FA, or whether a password reset is required.
This endpoint is typically used as the first step in the ITR Analyzer workflow to determine which sub-flow to invoke next — direct fetch, 2FA challenge, or password reset.
Key Benefits
Pre-Flight Validation — Confirms credential health before invoking billable downstream operations.
Smart Workflow Routing — Determines whether the next step is 2FA, password reset, or direct ITR retrieval.
Reduced User Friction — Surfaces credential issues early so end users can act before long waits.
Stateless Verification — Lightweight call suitable for periodic re-checks of stored credentials.

Use Cases#

Lending & NBFC
Accounting & Audit
Wealth & Tax Tech
Validate stored ITR credentials before triggering periodic income re-verification for existing borrowers.
Detect expired credentials early in loan application flows to prompt re-authentication.
Gate underwriting workflows on credential health to avoid mid-flow failures.

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 previously created via the ITR login flow that maps to stored taxpayer credentials.

Example Request#

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

Response Parameters#

ParameterTypeDescription
successbooleanIndicates whether the credential check completed successfully.
dataobjectContainer holding credential status fields.
data.client_idstringThe client identifier whose credentials were checked.
data.statusstringCredential status. Typical values include valid, invalid, expired, 2fa_required, password_reset_required.
data.messagestringHuman-readable explanation of the credential state.

Example Successful Response#

{
  "success": true,
  "data": {
    "client_id": "CLIENT_ID",
    "status": "valid",
    "message": "Credentials are valid and ready for ITR retrieval."
  }
}

Possible Error Responses#

Client Not Found
Unauthorized
Validation Error
Rate Limited
{
  "success": false,
  "error": {
    "code": "CLIENT_NOT_FOUND",
    "message": "No client exists for the supplied client_id."
  }
}
Returned when the client_id does not exist or belongs to a different tenant. Create the client first via the ITR login create-client endpoint.

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.
Never expose client_id to untrusted clients; restrict its use to trusted server-to-server contexts.
Log credential-check outcomes for audit but never log the underlying taxpayer credentials themselves.
Use separate API credentials for sandbox and production environments.
User Experience Guidelines
Call this endpoint at the start of any ITR-related workflow so users see issues immediately rather than mid-flow.
Map each status value to a clear next-step CTA: "Continue", "Verify OTP", "Reset Password", "Re-enter Credentials".
Cache valid credential states for a short window to avoid redundant calls within the same session.
Communicate password-reset and 2FA requirements with plain-language guidance, not raw error codes.
Avoid silently retrying when status indicates user action is required.

Code Samples#

cURL
Python
Node.js
Related APIs
ITR Login Create Client — Registers a new taxpayer credential set and returns the client_id consumed by this endpoint.
Generate 2FA OTP — Initiates the 2FA challenge when this endpoint reports 2fa_required.
Forget Password — Starts the password reset flow when this endpoint reports password_reset_required.
Compliance and Legal Considerations
This endpoint operates on stored ITR portal credentials associated with a client_id. Even though credentials themselves are not echoed back, the existence and status of those credentials constitute sensitive personal information under India's Digital Personal Data Protection Act, 2023 (DPDP Act) and the Information Technology Act, 2000. Restrict access to credential-status data on a need-to-know basis, log access for audit, and provide the underlying taxpayer with rights to review, update, and delete their stored credentials.

Request

Header Params

Responses

🟢200Success
application/json
Bodyapplication/json

Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.finpass.ai/api/v1/services/itr-analyzer/check-credentials' \
--header 'x-api-key;' \
--header 'x-api-secret;'
Response Response Example
{}
Previous
Create ITR Login Client
Next
Generate 2FA
Built with