BSA Batch Result

Endpoint Overview

GET /api/v1/bank/batch-result

Description

The BSA Batch Result endpoint retrieves the complete analysis results for a previously submitted bank statement batch. Given a batch_id, it returns the full processed output — including per-file transaction data, per-account bank group summaries, and a consolidated cross-bank analysis covering cash flow, average balances, account usage profiles, inter-account transfers, and entity-level financial intelligence.

The optional include_transactions flag controls whether individual transaction records are embedded in the response, allowing callers to fetch lightweight status checks or full data payloads depending on their use case.

Key Benefits

Complete Multi-Bank View: Retrieves consolidated analysis across all banks and accounts submitted in a single batch — SBI, ICICI, Kotak, and others in one response.

Flexible Transaction Inclusion: Toggle include_transactions=true/false to control payload size — fetch just analytics or full transaction-level detail.

Rich Cross-Bank Intelligence: Exposes cash flow, average balance by bank, entity-level turnover breakdown, primary banker identification, and suspicious pattern detection.

Structured Per-Account Grouping: Results are grouped by bank account with merged account info, statement period, discrepancy flags, and balance continuity checks.

Use Cases

Lending & Credit

Compliance & Audit

Accounting & Fintech

Underwriting systems polling this endpoint after batch submission to retrieve income, cash-flow, and average balance data for loan eligibility decisioning.

NBFC platforms consolidating multi-bank turnover and net position data to assess working capital limits for SME borrowers.

Technical Implementation

Authentication

All API requests must be authenticated using your API Key passed as a request header, along with a refresh token via the Cookie header.

Obtain API Credentials: Contact FinPass to receive your X-API-Key.

Obtain Refresh Token: Authenticate via the FinPass auth flow to receive a refresh_token cookie.

Include in Every Request: Add both to each API call as shown below.

Environment	Base URL
Production	`https://api.finpass.ai`

Header format:

X-API-Key: <YOUR_X_API_KEY>
Cookie: refresh_token=<YOUR_REFRESH_TOKEN>

⚠️ Never expose your X-API-Key or refresh_token in client-side code or public repositories. Always call this endpoint from a secure server-side environment.

Request Parameters

Request Headers

Header	Required	Description
`X-API-Key`	Yes	Your FinPass API key used for authentication.
`Cookie`	Yes	Must include `refresh_token=<token>` for session authentication.

Query Parameters

Parameter	Type	Required	Description
`batch_id`	String	Yes	The unique identifier of the batch whose results are to be retrieved. Returned as `batch_id` from the batch upload endpoint.
`include_transactions`	Boolean	No	When `true`, the response includes the full list of parsed transactions for each file in the batch. When `false` or omitted, transaction arrays are excluded. Default: `false`.

Example Request

Process Response

Top-Level Response Fields

Field	Type	Description
`success`	Boolean	`true` if the request was processed successfully.
`status_code`	Integer	HTTP status code of the operation (e.g., `200`).
`message`	String	Human-readable result message (e.g., `"Batch processing completed successfully"`).
`message_code`	String	Machine-readable status code (e.g., `"completed"`).
`data`	Object	The main payload containing all batch result details. See sub-fields below.

`data` Object Fields

Field	Type	Description
`batch_id`	String	Unique identifier of the batch.
`batch_type`	String	Type of batch — e.g., `"multi_bank"` for batches spanning multiple banks/accounts.
`status`	String	Overall batch processing status: `"completed"`, `"processing"`, or `"failed"`.
`created_at`	String (ISO 8601)	Timestamp when the batch was created.
`updated_at`	String (ISO 8601)	Timestamp of the last batch status update.
`user_email`	String	Email address associated with the batch submission.
`total_files`	Integer	Total number of files submitted in the batch.
`processed_files`	Integer	Number of files successfully processed.
`failed_files`	Integer	Number of files that failed during processing.
`files`	Array	Array of per-file result objects. See `files[]` fields below.
`bank_count`	Integer	Total number of distinct bank accounts identified across all files.
`bank_groups`	Array	Array of per-account group objects. See `bank_groups[]` fields below.
`cross_bank_analysis`	Object	Consolidated multi-bank analysis. See `cross_bank_analysis` fields below.
`filter_from_date`	String \| null	Date filter applied to transactions (if any).
`filter_to_date`	String \| null	Date filter applied to transactions (if any).
`analysis_url`	String	Path or URL to the generated Excel analysis report.
`analysis_json_url`	String	Path or URL to the generated JSON analysis report.
`analysis_pdf_s3_url`	String	Path or URL to the generated PDF analysis report.
`cross_bank_analysis_url`	String \| null	URL to a separate cross-bank analysis file, if generated.
`entity_type`	String	Entity classification — e.g., `"entity"` for a business.
`mismatched_sequence_date`	Array	List of transactions where date sequencing anomalies were detected.
`negative_balance`	Array	List of transactions where a negative balance was recorded.
`discrepancies`	Object	Summary of detected data quality issues. Contains `balance_errors`, `swapped_credit_debit_rows`, and `corrected_row_indices`.
`error_message`	String \| null	Error detail if the batch or analysis failed; `null` on success.
`input_s3_url`	String \| null	S3 URL of the original uploaded files, if stored.

`files[]` Object Fields

Field	Type	Description
`client_id`	String	Unique identifier for this individual statement file.
`status`	String	Processing status of this file: `"completed"` or `"failed"`.
`batch_sequence`	Integer	Zero-based index of this file in the batch submission order.
`bank_name`	String	Detected bank name (e.g., `"sbi"`, `"icici"`, `"kotak_mahindra_bank"`).
`account_number`	String	Bank account number extracted from the statement.
`transaction_count`	Integer	Total number of transactions parsed from this file.
`error_message`	String \| null	Error detail if this file failed processing; `null` on success.
`transactions`	Array	List of transaction objects (present only when `include_transactions=true`). See `transactions[]` fields below.

`transactions[]` Object Fields

Field	Type	Description
`sr_no`	Integer	Serial number / row index of the transaction within the statement.
`txn_date`	String	Transaction date in `DD-MM-YY` format.
`value_date`	String	Value date (effective date) of the transaction in `DD-MM-YY` format.
`reference_no`	String	Bank-assigned reference or UTR number for the transaction. Empty string if not available.
`description`	String	Full transaction narrative as extracted from the statement.
`txn_type`	String	Transaction direction: `"Cr."` for credit or `"Dr."` for debit.
`credit`	Number \| String	Credit amount in INR. Empty string `""` if this is a debit transaction.
`debit`	Number \| String	Debit amount in INR. Empty string `""` if this is a credit transaction.
`balance`	Number	Running account balance after this transaction, in INR.

`bank_groups[]` Object Fields

Field	Type	Description
`group_id`	String	Unique identifier for this bank account group (e.g., `"grp_435ffec9"`).
`bank_name`	String	Name of the bank for this group.
`account_number`	String	Account number for this group.
`account_type`	String	Account classification (e.g., `"Current"`). Empty string if not detected.
`file_client_ids`	Array	List of `client_id` values from `files[]` that belong to this group.
`period_start`	String (ISO 8601)	Start of the statement period covered by this group.
`period_end`	String (ISO 8601)	End of the statement period covered by this group.
`merged_account_info`	Object	Consolidated account metadata extracted from the statements. See sub-fields below.
`transaction_count`	Integer	Total transaction count across all files in this group.
`bank_analysis`	Object	Analysis status and reference. Contains `status`, `analysis_client_id`, and `merged_analysis`.
`discrepancies`	Object	Data quality issues detected for this account group.
`balance_continuity_errors`	Array	List of continuity errors where the closing balance of one transaction doesn't match the opening of the next.
`warnings`	Array	Non-critical flags or observations about this account group.

`merged_account_info` Sub-fields

Field	Type	Description
`bank_name`	String	Bank name.
`account_holder_name`	String	Name of the account holder as on the statement.
`account_number`	String	Full account number.
`address`	String	Registered address of the account holder.
`ifsc`	String	IFSC code of the branch.
`micr_code`	String	MICR code of the branch.
`customer_id`	String	Bank-assigned customer ID.
`ckyc_number`	String	CKYC number if available.
`email`	String	Email on record with the bank.
`phone`	String	Phone number on record with the bank.
`pincode`	String	Pincode of the registered address.
`generation_date`	String	Date the statement was generated (DD-MM-YY).
`product_type`	String	Bank product type if mentioned on the statement.
`account_type`	String	Account type (e.g., `"Current"`).
`account_open_date`	String	Date the account was opened, if available.
`is_nominee`	String	Nominee details if present on the statement.
`branch_name`	String	Name of the branch.
`branch_address`	String	Address of the branch.
`joint_holder_name`	String	Name of the joint account holder, if applicable.
`statement_period`	Object	Contains `from` and `to` fields (DD-MM-YY) representing the statement period.

`cross_bank_analysis` Object Fields

Field	Type	Description
`summary`	Object	High-level summary: `bank_count`, `account_count`, `total_transactions`, `entity_type`, `analysis_timestamp`.
`cash_flow`	Object	Aggregated cash flow: `total_inflows`, `total_outflows`, `net_cash_flow`, `adjusted_net_cash_flow`, `inflows_by_bank`, `outflows_by_bank`.
`inter_account_transfers`	Object	Detected transfers between accounts in the batch: `transfers`, `total_amount`, `transfer_count`.
`salary_analysis`	Object	Salary credit detection: `total_salary_credited`, `salary_by_bank`, `primary_salary_account`, `multiple_salary_sources`.
`emi_analysis`	Object	EMI outflow detection: `total_emi_outflow`, `emi_by_bank`, `banks_with_emi`.
`account_usage_profile`	Object	Per-account usage classification (`mixed`, `income`, `expense`) with credits, debits, and transaction counts. Also includes `income_primary_accounts`, `expense_primary_accounts`, `suggested_salary_account`.
`suspicious_patterns`	Object	Flags for `circular_flows` and `duplicate_payments`.
`entity_analysis`	Object	Full entity-level consolidated analysis. See sub-fields below.
`is_single_bank_multi_account`	Boolean	`true` if all accounts in the batch belong to the same bank.

`entity_analysis` Sub-fields

Field	Type	Description
`consolidated_summary`	Object	Combined totals: `total_banks`, `total_accounts`, `bank_names`, `combined_latest_balance`, `total_credit_turnover`, `total_debit_turnover`, `net_position`, `period_start`, `period_end`.
`bank_wise_turnover`	Array	Per-account breakdown of credit/debit turnover, percentages, transaction count.
`combined_abb`	Object	Average balance analysis: `combined_weighted_abb`, `total_abb_across_banks`, `total_min_balance`, `total_max_balance`, and `bank_wise_abb` array with per-account average, min, and max balances.
`primary_banker`	Object	Identifies the primary operating account based on highest combined turnover, salary-receiving account, EMI-paying account, and a text `recommendation`.
`bank_comparison`	Array	Side-by-side comparison of all accounts: credit/debit turnover, net flow, transaction count, average/min/max balance, usage type, and statement period.
`inter_account_summary`	Object	Summary of inter-account transfers: `total_transfers`, `total_amount`, `net_flow_direction`, `round_tripping_detected`, `transfer_pairs`.

Example Successful Response

{
  "success": true,
  "status_code": 200,
  "message": "Batch processing completed successfully",
  "message_code": "completed",
  "data": {
    "batch_id": "batch_ac07698a2901",
    "batch_type": "multi_bank",
    "status": "completed",
    "created_at": "2026-06-02T07:27:51.970000",
    "updated_at": "2026-06-02T07:28:05.485000",
    "user_email": "test@example.com",
    "total_files": 4,
    "processed_files": 4,
    "failed_files": 0,
    "bank_count": 4,
    "entity_type": "entity",
    "files": ["... per-file objects with transactions ..."],
    "bank_groups": ["... per-account group objects ..."],
    "cross_bank_analysis": {
      "summary": {
        "bank_count": 4,
        "account_count": 4,
        "total_transactions": 201,
        "entity_type": "entity",
        "analysis_timestamp": "2026-06-02T07:28:03.746663"
      },
      "cash_flow": {
        "total_inflows": 186497708.59,
        "total_outflows": 189879688.92,
        "net_cash_flow": -3381980.33,
        "adjusted_net_cash_flow": -3381980.33,
        "inflows_by_bank": {
          "sbi_00000041643542357": 36679382.0,
          "icici_135305001422": 133057879.0
        },
        "outflows_by_bank": {
          "sbi_00000041643542357": 42658463.88,
          "icici_135305001422": 130822373.04
        }
      }
    },
    "discrepancies": {
      "balance_errors": [],
      "swapped_credit_debit_rows": 0,
      "corrected_row_indices": []
    },
    "mismatched_sequence_date": [],
    "negative_balance": [],
    "error_message": null,
    "analysis_url": "/storage/analysis_bank_statement_e6793b6b5c92.xlsx",
    "analysis_json_url": "/storage/analysis_bank_statement_e6793b6b5c92.json",
    "analysis_pdf_s3_url": "/storage/analysis_bank_statement_e6793b6b5c92.pdf",
    "filter_from_date": null,
    "filter_to_date": null,
    "cross_bank_analysis_url": null,
    "input_s3_url": null
  }
}

Possible Error Responses

401 Unauthorized

400 Bad Request

404 Not Found

202 Processing

500 Internal Server Error

{
  "success": false,
  "status_code": 401,
  "message": "Invalid or missing API credentials.",
  "message_code": "unauthorized"
}

Returned when X-API-Key is absent or invalid, or the refresh_token cookie is missing or expired. Re-authenticate to obtain a fresh token and retry.

Integration Best Practices

Security Recommendations

Server-side only: Always call this endpoint from your backend. Never expose X-API-Key or refresh_token in browser JavaScript or mobile app code.

Token rotation: Refresh tokens have limited lifetimes. Implement a token refresh flow and handle 401 responses gracefully by re-authenticating before retrying.

Secure result storage: The response contains sensitive financial data. Encrypt and access-control any persisted results in your own systems.

Use HTTPS exclusively: Always use https:// for all requests to ensure data in transit is encrypted end-to-end.

User Experience Guidelines

Poll with back-off: If the batch is still "processing", retry the endpoint with exponential back-off (e.g., 5s → 10s → 20s) rather than hammering the API. Check processed_files vs total_files to show progress.

Use include_transactions=false for status checks: Fetch lightweight status and analytics first; only request full transaction data when the user needs it to reduce payload size and latency.

Surface cross-bank insights: Prioritise displaying cross_bank_analysis.cash_flow, combined_abb, and primary_banker.recommendation — these are the highest-value outputs for most lending and compliance use cases.

Handle partial failures: When failed_files > 0, check files[].error_message for each failed file and surface actionable feedback so users can re-upload affected statements.

Store analysis_url links: The Excel, JSON, and PDF report URLs point to generated analysis files. Surface these as downloads to users who need a printable or offline report.

Code Samples

cURL

Python

Node.js

PHP

Related APIs

BSA Upload Statements Batch — Submit one or more bank statement PDFs or ZIP archives to create a batch for analysis. Returns the batch_id used to poll this endpoint.

BSA Single Statement Upload — Upload a single bank statement for analysis when multi-file batching is not required.

BSA Analysis Status — Lightweight endpoint to check only the processing status of a batch without fetching the full result payload.

Customer KYC Verification — Verify identity documents alongside bank statement analysis as part of a complete onboarding or lending workflow.

Compliance and Legal Considerations

Data Privacy: The response contains highly sensitive personal and financial information including account numbers, holder names, transaction histories, and balance data. Ensure your handling of this data complies with DPDP (India), GDPR (EU), or the applicable data protection framework in your jurisdiction.

Access Control: Restrict access to batch results to only authorised personnel or systems. Implement role-based access controls in your application layer before exposing any result data.

Retention Policy: Do not retain raw transaction data beyond the period required for your business purpose. Define and enforce a data retention and deletion policy.

Token Security: The refresh_token cookie grants authenticated access to financial data. Treat it with the same care as a password — store securely, never log, and invalidate on logout or suspected compromise.

Audit Trails: Retain logs of all API calls to this endpoint — including batch_id, requesting user, and timestamp — to support audit, dispute resolution, and regulatory requirements.

Batch Result

BSA Batch Result#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Example Request#

Top-Level Response Fields#

data Object Fields#

files[] Object Fields#

transactions[] Object Fields#

bank_groups[] Object Fields#

merged_account_info Sub-fields#

cross_bank_analysis Object Fields#

entity_analysis Sub-fields#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses