Bank Statement OCR API
New
Read a bank statement and get the account header and dated transaction rows back as structured data for lending and underwriting review.
Overview
Bank Statement OCR reads an uploaded statement and returns the account header and the transaction rows as structured data. Your credit team works from a table instead of reading down a page. A reading may cover account and branch details, the statement period, and opening and closing balances. It can also return dated rows carrying narration, amount and running balance. The files that arrive are not uniform. Net banking downloads, branch printouts, photographs and protected exports all reach the same underwriting queue, and every bank formats its statement differently. Available fields and rows vary by data source, bank layout and file condition. A statement is one of the most revealing documents a person can share. Collect it for a stated purpose with recorded consent, and use it only for the assessment consented to. Keep the source document linked to the rows so you can explain a decision later.
- Category
- Document OCR APIs
- Coverage
- Statements from Indian banks; what can be read depends on the file, the bank layout and image quality
- Input
- A bank statement uploaded by the applicant, including net banking downloads, scanned printouts and photographed pages
- Output
- Structured account header fields and dated transaction rows carrying narration, debit or credit amount and running balance
- Typical users
- Banks and NBFCs, fintech lending platforms, marketplaces offering seller finance, commercial vehicle financiers, insurers
- Coverage note
- Available fields and rows vary by bank statement layout, file condition and data source. A reading structures the evidence; it does not make the credit decision.
The overview and the sections after the reference are the FinSour API catalog’s own record for this service, rendered unaltered.
Endpoint URL and method
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Authentication
Send your API key in this header on every call, from your own server: a key sent from a browser is refused. A key starting fs_test_ calls the sandbox and one starting fs_live_ calls production, at the same address. Create keys in the FinSour console.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Request parameters
Headers
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
Idempotency-Key | string | Required | A key you generate for each attempt. Sending the same key again returns the first answer instead of running the check twice; the same key with a different body is refused. | 8 to 255 characters. Matches ^[A-Za-z0-9._:-]+$ |
FinSour-Version | string | Required | Send 2026-11-01 on this call and on every poll to get the receipt and the result described on this page. A call without it is served under 2026-09-01, whose job has a different shape. | — |
Body
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
file | file | Required | The document to read. | — |
payload | string (JSON) | Required | A JSON string carrying the call's options. | — |
payload. | object | Required | Settings for this call. This API requires consent. | — |
payload. | string | Optional | Your own reference for this call. It comes back unchanged as meta.reference. | 1 to 128 characters |
payload. | object | Required | The person's consent to this check. | — |
payload. | boolean | Required | Send true once the person has agreed to the check. | Always true |
payload. | string (date-time) | Required | When the person gave consent. | — |
payload. | string | Required | What the check is for, for example kyc. | 1 to 64 characters |
Request samples
cURL
curl -X POST https://gateway.staging.finsour.io/v1/documents/bank-statement \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "FinSour-Version: 2026-11-01" \
-F "file=@<path-to-document>" \
-F 'payload={"options":{"consent":{"obtained":"<obtained>","at":"<at>","purpose":"<purpose>"}}}'Node.js
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("file", await openAsBlob("<path-to-document>"));
form.append("payload", JSON.stringify({
"options": {
"consent": {
"obtained": "<obtained>",
"at": "<at>",
"purpose": "<purpose>"
}
}
}));
const response = await fetch("https://gateway.staging.finsour.io/v1/documents/bank-statement", {
method: "POST",
headers: {
"X-Api-Key": process.env.FINSOUR_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"FinSour-Version": "2026-11-01",
},
body: form,
});
console.log(response.status, await response.json());Python
import os
import uuid
import json
import requests
response = requests.post(
"https://gateway.staging.finsour.io/v1/documents/bank-statement",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
"FinSour-Version": "2026-11-01",
},
files={"file": open("<path-to-document>", "rb")},
data={"payload": json.dumps({
"options": {
"consent": {
"obtained": "<obtained>",
"at": "<at>",
"purpose": "<purpose>",
},
},
})},
timeout=30,
)
print(response.status_code, response.json())Generated from the fields above. Replace each value in angle brackets with your own; the key is read from FINSOUR_API_KEY.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Response schema
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
data | object | Always | The job that will read the document. | — |
data. | string | Always | The job's id. Poll GET /v1/jobs/{jobId} with it. | Matches ^[0-9A-HJKMNP-TV-Z]{26}$ |
data. | string | Always | Always queued: the job is accepted and has not started. | Always "queued" |
The result
Poll GET /v1/jobs/{jobId}. Once the job has finished, data holds these fields:
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
jobId | string | Always | — | — |
status | string | Always | — | One of queued, processing, completed, needs_review, unreadable, failed, expired, cancelled |
documentType | string or null | Always | The kind of document found, once it has been read; null before that. | — |
confidence | number or null | Always | The document's confidence, 0 to 1, to two places; null until it has been read. | Minimum 0. Maximum 1 |
fields | object | Always | What was read. Every key is always present: null means the document does not carry it, or it could not be read with enough confidence. | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | string or null | Always | Decimal rupees as text, for example "12345.50". | — |
fields. | string or null | Always | Decimal rupees as text, for example "12345.50". | — |
fields. | array of objects | Always | — | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | Decimal rupees as text, for example "12345.50". | — |
fields. | string or null | Always | Decimal rupees as text, for example "12345.50". | — |
fields. | string or null | Always | Decimal rupees as text, for example "12345.50". | — |
fieldsToReview | array of strings | Always | When status is needs_review, the fields a person should confirm; empty otherwise. | — |
failureReason | string | Sometimes | Present only when status is unreadable or failed. | One of UNREADABLE_IMAGE, LOW_CONFIDENCE, DOCUMENT_TYPE_MISMATCH, UNSUPPORTED_MEDIA_TYPE, FILE_TOO_LARGE, INPUT_CORRUPT, PAGE_LIMIT_EXCEEDED, TIMEOUT, PROCESSING_ERROR |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Error codes
| Code | Status | Meaning | Retrying |
|---|---|---|---|
API_VERSION_UNSUPPORTED | 400 | That API version is no longer supported. | Do not retry automatically |
IDEMPOTENCY_KEY_INVALID | 400 | That Idempotency-Key does not meet the required format. | Do not retry automatically |
IDEMPOTENCY_KEY_REQUIRED | 400 | An Idempotency-Key header is required for this request. | Do not retry automatically |
REQUEST_MALFORMED | 400 | The request could not be parsed. | Do not retry automatically |
AUTH_KEY_EXPIRED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_INVALID | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_MISSING | 401 | No API key was presented. | Do not retry automatically |
AUTH_KEY_REVOKED | 401 | The API key is not valid. | Do not retry automatically |
INSUFFICIENT_BALANCE | 402 | The available balance is not enough for this request. | Do not retry automatically |
AUTH_IP_NOT_ALLOWED | 403 | This API key may not be used from this address. | Do not retry automatically |
ENTITLEMENT_MISSING | 403 | This organization is not entitled to that product in this environment. | Do not retry automatically |
ORGANIZATION_SUSPENDED | 403 | This organization is not active. | Do not retry automatically |
PRODUCT_NOT_AVAILABLE | 403 | That product is not available. | Do not retry automatically |
PRODUCT_RETIRED | 403 | That product has been withdrawn. | Do not retry automatically |
SCOPE_INSUFFICIENT | 403 | This API key does not carry the scope this product requires. | Do not retry automatically |
PRODUCT_NOT_FOUND | 404 | No such product. | Do not retry automatically |
IDEMPOTENCY_KEY_REUSED | 409 | That idempotency key was already used for a different request. | Do not retry automatically |
PRICE_UNAVAILABLE | 409 | No active price covers this product right now. | Safe to retry |
REQUEST_IN_PROGRESS | 409 | An earlier attempt with this key is still running. | Safe to retry |
SETTLEMENT_PENDING | 409 | This request is awaiting reconciliation by an operator. | Do not retry automatically |
API_VERSION_SUNSET | 410 | That API version passed its announced sunset date. | Do not retry automatically |
REQUEST_TOO_LARGE | 413 | The request body is too large. | Do not retry automatically |
OCR_UNSUPPORTED_MEDIA_TYPE | 415 | That document format is not accepted. | Do not retry automatically |
UNSUPPORTED_MEDIA_TYPE | 415 | That content type is not accepted on this route. | Do not retry automatically |
CONSENT_REQUIRED | 422 | This product requires an explicit consent flag. | Do not retry automatically |
SANDBOX_FIXTURE_MISSING | 422 | No sandbox fixture exists for this input. Use a different test value. | Do not retry automatically |
UPSTREAM_REJECTED | 422 | The upstream source rejected the input. | Do not retry automatically |
VALIDATION_FAILED | 422 | The request payload is invalid. | Do not retry automatically |
CONCURRENCY_LIMIT | 429 | Too many simultaneous requests. | Safe to retry |
OCR_QUEUE_SATURATED | 429 | The document queue is full. Retry shortly. | Safe to retry |
QUOTA_EXCEEDED | 429 | The allowance for this window is spent. | Do not retry automatically |
RATE_LIMITED | 429 | Too many requests. | Safe to retry |
INTERNAL_ERROR | 500 | An unexpected error occurred. | Safe to retry |
OUTCOME_UNCERTAIN | 502 | The outcome of this request is not yet known. Retry with the same Idempotency-Key. | Do not retry automatically |
UPSTREAM_UNAVAILABLE | 502 | The upstream source is unavailable. Retry shortly. | Safe to retry |
MAINTENANCE_MODE | 503 | The service is in a maintenance window. | Safe to retry |
NO_PROVIDER_AVAILABLE | 503 | No provider can serve this product right now. | Safe to retry |
OCR_UNAVAILABLE | 503 | Document reading is unavailable right now. Retry later. | Safe to retry |
SERVICE_OVERLOADED | 503 | The service is shedding load. Retry shortly. | Safe to retry |
UPSTREAM_TIMEOUT | 504 | The upstream source did not respond in time. | Safe to retry |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Rate limits
| Scope | Limit | Window | At the limit |
|---|---|---|---|
| Your API key, within your organisation's limit | The figure in X-RateLimit-Limit | Per minute | 429 RATE_LIMITED, with Retry-After in seconds. Every answer past authentication carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Use cases
- Lending and NBFCs: structure statement rows as evidence of income, obligations and repayment behavior
- Fintech lending: process a statement inside a short-tenure credit journey at application
- Marketplaces: underwrite seller working-capital offers on settlement inflows and account activity
- Logistics and fleet: assess transporter and commercial vehicle finance on operating inflows
- Real estate and leasing: check home loan, tenant and lease affordability against statement data
- Insurance: sense-check declared income during financial underwriting for high-value covers
What this service does
Turns a statement into a table
Account and branch details, the statement period, opening and closing balances and dated transaction rows come back as structured data. Questions about inflows, obligations and balance behavior become queries instead of an afternoon of reading. The fields on offer depend on the layout, the file and the data source.
Takes the files that actually arrive
One application file may hold a net banking download, a stamped branch printout, a photograph of several pages and a protected export. The reading is built for that spread.
Balances you can reconcile the rows against
The reading returns opening and closing balances alongside the rows. You can check the extracted table against the statement itself. Send a file that does not agree to a reviewer instead of into a rule.
Evidence stays attached to the decision
Keep the source document linked to the structured rows and an underwriter can trace any figure back to the page it came from. That is what a credit file needs when someone reviews or challenges the decision.
How a check runs
Collect the statement and its password
The applicant uploads the statement through your origination journey. Where the file is protected, ask for the password in the same step.
Send the file for reading
Your loan origination or underwriting system sends the document to the API, including multi-page and multi-account submissions on one case.
Get the header and the dated rows
The response returns the account header and the dated rows it could read. Available fields and rows vary by bank layout, file condition and data source.
Reconcile the rows against the balances
Check the extracted rows against the stated opening and closing balances. Send a file that does not agree to a human reviewer.
Pass the table into underwriting
Structured rows feed your scorecard, policy checks or credit note. Keep the source document linked so any figure can be traced back to its page.
Questions
- What is a Bank Statement OCR API?
- An interface that accepts a bank statement document and returns the account header and the transaction rows as structured data. Your lending or underwriting system works from a table. A credit officer no longer reads the pages and keys in the figures.
- What data do I get from a bank statement reading?
- The response may carry account and branch details, the account holder name, the statement period, and opening and closing balances. It may also carry transaction rows with date, narration, debit or credit amount and running balance. The fields and rows on offer depend on the data source, the bank layout and the condition of the file.
- Can it read a scanned or photographed statement?
- Yes, reading works on scanned and photographed documents as well as text-based files, but quality tells. A skewed page, a torn column edge or a photograph taken under a lamp can obscure part of a balance column. That is why reconciling the extracted rows against the stated balances is worth building into the flow.
- Does statement OCR replace consent-led account data sharing?
- No, the two sit alongside each other. Where a customer permits their bank to share account data directly, that channel gives data from the source. Document reading covers the many applicants who still arrive with a file in hand, and most lenders support both paths into the same underwriting queue.
- Does the API decide whether to approve the loan?
- No, it structures the evidence. Your scorecards, policy rules and a human reviewer make the decision. Keeping the source document linked to the structured rows is what lets you explain and review that decision afterwards.
- What consent and privacy rules apply to a bank statement?
- A statement reveals income, spending, obligations and a great deal about a person besides. Collect it only for a stated, lawful purpose, with the account holder's informed consent recorded against the file, and use it only for that assessment. Restrict access to the staff who need it, log who opens it, and retain it no longer than your policy and applicable law require.
Catalog entry last updated .