Bank Statement Result API

Endpoint Overview

POST /api/v1/services/bank/statement-result?client_id={{client_id}}

Description

The Bank Statement Result API retrieves the comprehensive analysis results of a previously submitted bank statement. This endpoint returns detailed account information, transaction history, and analysis insights extracted from the uploaded bank statement document. It serves as the retrieval mechanism in an asynchronous bank statement processing workflow, allowing developers to fetch processed data once document analysis is complete.

This API is essential for financial technology applications that require automated extraction and validation of banking data from statement documents, enabling streamlined verification processes without manual data entry.

Key Benefits

Comprehensive Data Extraction: Automatically extracts account holder details, bank information, and complete transaction history from statement documents

Data Quality Assurance: Identifies balance discrepancies, negative balances, and mismatched sequence dates for data integrity validation

Flexible Output Formats: Provides analysis results in both Excel and JSON formats via pre-signed URLs for easy integration

Transaction Categorization: Returns structured transaction data with credit/debit classification, reference numbers, and running balances

Use Cases

Banking & Lending

Fintech & Payments

Insurance & Wealth Management

Loan Underwriting: Retrieve parsed bank statements to assess applicant's financial health, income patterns, and spending behavior for credit decisions

Account Verification: Validate customer-provided bank account details against extracted statement information during onboarding

Cash Flow Analysis: Analyze transaction patterns to determine creditworthiness and repayment capacity for loan applications

Technical Implementation

Authentication

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

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

Different authentication tokens are used for sandbox and production environments:

Production: https://api.finpass.ai

Request Parameters

Request Headers

Header	Required	Description
Content-Type	Yes	Must be set to `application/json`
X-API-Key	Yes	Your unique API key provided by Finpass
X-API-Secret	Yes	Your API secret key provided by Finpass

Query Parameters

Parameter	Type	Required	Description
client_id	string	Yes	The unique client identifier returned from the initial bank statement upload request. This ID is used to retrieve the specific statement analysis results.

Request Body

This endpoint does not require a request body. The client_id query parameter is used to identify the statement to retrieve.

Example Request

{}

Process Response

Response Parameters

Parameter	Type	Description
doc_id	string	Unique document identifier for the service log entry
client_id	string	Client identifier for the bank statement processing request
status	string	Current processing status (e.g., "completed", "processing", "failed")
checkpoint	string	Current processing checkpoint (e.g., "analysing_completed")
progress	number/null	Processing progress percentage, null when completed
error_message	string/null	Error message if processing failed, null on success
account_info	object	Extracted bank account information object
account_info.bank_name	string	Name of the bank
account_info.account_holder_name	string	Name of the account holder
account_info.account_number	string	Bank account number
account_info.address	string	Bank branch address
account_info.ifsc	string	IFSC code of the bank branch
account_info.micr_code	string	MICR code for the bank branch
account_info.customer_id	string	Customer ID assigned by the bank
account_info.ckyc_number	string	Central KYC number if available
account_info.email	string	Email address associated with the account
account_info.phone	string	Phone number(s) associated with the account
account_info.pincode	string	PIN code of the branch location
account_info.generation_date	string	Date when the statement was generated
account_info.product_type	string	Type of banking product
account_info.account_type	string	Type of account (savings, current, etc.)
account_info.account_open_date	string	Date when the account was opened (DD-MM-YY format)
account_info.is_nominee	string	Whether a nominee is registered ("Yes"/"No")
account_info.branch_name	string	Name of the bank branch
account_info.branch_address	string	Full address of the bank branch
account_info.joint_holder_name	string	Name of joint account holder if applicable
account_info.statement_period	object	Statement period details
account_info.statement_period.from	string	Statement start date (DD-MM-YY format)
account_info.statement_period.to	string	Statement end date (DD-MM-YY format)
transactions	array	Array of transaction objects
transactions[].sr_no	integer	Serial number of the transaction
transactions[].txn_date	string	Transaction date (DD-MM-YY format)
transactions[].value_date	string	Value date of the transaction (DD-MM-YY format)
transactions[].reference_no	string	Transaction reference number
transactions[].description	string	Transaction description/narration
transactions[].txn_type	string	Transaction type ("Cr." for credit, "Dr." for debit)
transactions[].credit	number	Credit amount (0 if debit transaction)
transactions[].debit	number	Debit amount (0 if credit transaction)
transactions[].balance	number	Running balance after the transaction
mismatched_sequence_date	array	Array of transactions with date sequence mismatches
negative_balance	array	Array of transactions resulting in negative balance
discrepancies	object	Object containing data quality issues
discrepancies.balance_errors	array	Array of balance calculation errors found
discrepancies.swapped_credit_debit_rows	number	Count of rows with swapped credit/debit values
discrepancies.corrected_row_indices	array	Indices of rows that were auto-corrected
analysis_completed	boolean	Whether the analysis has been completed
analysis_result	object/null	Additional analysis results if applicable
analysis_url	string	Pre-signed S3 URL to download analysis in Excel format
analysis_json_url	string	Pre-signed S3 URL to download analysis in JSON format

Example Successful Response

{
  "doc_id": "svclog_697b1659_b5c92",
  "client_id": "bank_statement_5fde11",
  "status": "completed",
  "checkpoint": "analysing_completed",
  "progress": null,
  "error_message": null,
  "account_info": {
    "bank_name": "hdfc",
    "account_holder_name": "Modi Kumar",
    "account_number": "5010123456678",
    "address": "HDFC BANK LTD, INDIA",
    "ifsc": "HDFC0001234",
    "micr_code": "323212345",
    "customer_id": "213431234",
    "ckyc_number": "",
    "email": "USER@GMAIL.COM",
    "phone": "18002600/18001600",
    "pincode": "",
    "generation_date": "",
    "product_type": "",
    "account_type": "",
    "account_open_date": "01-12-22",
    "is_nominee": "Yes",
    "branch_name": "",
    "branch_address": "",
    "joint_holder_name": "",
    "statement_period": {
      "from": "01-09-24",
      "to": "28-02-25"
    }
  },
  "transactions": [
    {
      "sr_no": 1,
      "txn_date": "30-09-24",
      "value_date": "30-09-24",
      "reference_no": "HSBCN2123123456789",
      "description": "NEFT CR-HSBC0400002-TELEPERFORMANCE GLOB AL BUSINESS PRI-KUMAR VISVAS- 26978",
      "txn_type": "Cr.",
      "credit": 31183,
      "debit": 0,
      "balance": 31183.04
    },
    {
      "sr_no": 2,
      "txn_date": "30-09-24",
      "value_date": "30-09-24",
      "reference_no": "0000136312342546",
      "description": "UPI-RAJIV TALWAR-Q61234556@YBL-YESB0Y BLUPI-136335544943-PAYMENT FROM PHONE",
      "txn_type": "Dr.",
      "credit": 0,
      "debit": 420,
      "balance": 30763.04
    },
    {
      "sr_no": 3,
      "txn_date": "01-10-24",
      "value_date": "30-09-24",
      "reference_no": "000000000000000",
      "description": "INTEREST PAID TILL 30-SEP-2024",
      "txn_type": "Cr.",
      "credit": 4,
      "debit": 0,
      "balance": 30767.04
    },
    {
      "sr_no": 4,
      "txn_date": "01-10-24",
      "value_date": "01-10-24",
      "reference_no": "00004275200000000",
      "description": "UPI-RAJIV KUMAR-9876543210@AXL-BARB0 MANJAI-12344665788855-UPI",
      "txn_type": "Dr.",
      "credit": 0,
      "debit": 860,
      "balance": 29907.04
    },
    {
      "sr_no": 4,
      "txn_date": "01-10-24",
      "value_date": "01-10-24",
      "reference_no": "00004275200000000",
      "description": "UPI-RAJIV KUMAR-9876543210@AXL-BARB0 MANJAI-12344665788855-UPI",
      "txn_type": "Dr.",
      "credit": 0,
      "debit": 100,
      "balance": 29807.04
    },
    {
      "sr_no": 5,
      "txn_date": "02-10-24",
      "value_date": "02-10-24",
      "reference_no": "0000427669690532",
      "txn_type": "Dr.",
      "description": "UPI-John Doe-PAYTMQR5F5L0U@PTYS-YESB0P TMUPI-421234454356-UPI",
      "credit": 0,
      "debit": 20,
      "balance": 29729.04
    }
  ],
  "mismatched_sequence_date": [],
  "negative_balance": [],
  "discrepancies": {
    "balance_errors": [],
    "swapped_credit_debit_rows": 0,
    "corrected_row_indices": []
  },
  "analysis_completed": true,
  "analysis_result": null,
  "analysis_url": "https://finpass-bucket.s3.amazonaws.com/bank-statements/analysis_bank_statement_5fde11211d78.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAY5K3QRM5GCBANPUS%2F20260131%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260131T064010Z&X-Amz-Expires=",
  "analysis_json_url": "https://finpass-bucket.s3.amazonaws.com/bank-statements/analysis_bank_statement_5fde11211d78.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAY5K3QRM5GCBANPUS%2F20260131%2Fap-south-1%2Fs3%2"
}

Possible Error Responses

Invalid Client ID

Processing In Progress

Processing Failed

Authentication Error

{
  "status": "error",
  "error_message": "Invalid client_id provided. No matching statement found.",
  "doc_id": null,
  "client_id": "invalid_client_id"
}

This error occurs when the provided client_id does not match any existing bank statement processing request in the system.

Integration Best Practices

Security Recommendations

Secure Credential Storage: Store your X-API-Key and X-API-Secret in environment variables or a secure secrets manager; never hardcode them in source code

Token Management: Implement proper JWT token refresh mechanisms to handle token expiration gracefully without service interruption

Data Encryption: Ensure all API communications occur over HTTPS and encrypt sensitive banking data at rest in your application

Access Controls: Implement role-based access controls to restrict who can access bank statement data within your organization

Audit Logging: Maintain comprehensive logs of all API calls for compliance and security auditing purposes

User Experience Guidelines

Implement Polling Wisely: Use exponential backoff when polling for results to avoid overwhelming the API while providing timely updates to users

Progress Indicators: Display the checkpoint and progress values to keep users informed about the processing status of their statements

Error Handling: Provide clear, user-friendly error messages when processing fails, and offer guidance on how to resolve common issues

Data Validation: Validate extracted data against user-provided information and highlight discrepancies for manual review

Download Options: Offer users the ability to download analysis results in both Excel and JSON formats using the provided pre-signed URLs

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Data Privacy: Bank statements contain sensitive financial information. Ensure your application complies with applicable data protection regulations such as the Information Technology Act, 2000 and RBI guidelines on data localization.

Consent Management: Obtain explicit consent from customers before processing their bank statements. Maintain records of consent for audit purposes.

Data Retention: Implement appropriate data retention policies. The pre-signed URLs for analysis downloads expire after a limited time; download and securely store required data within your compliance framework.

PCI DSS Compliance: If processing payment card data extracted from statements, ensure your systems comply with PCI DSS requirements.

Audit Trail: Maintain comprehensive logs of all API interactions for regulatory compliance and dispute resolution purposes.

Third-Party Sharing: Do not share extracted bank statement data with unauthorized third parties without explicit customer consent.

Statement Result

Bank Statement Result API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses