Documents
Send a statement, list what was read, fetch one result, delete it, and download a collection upload's original file.
| Method and path | Does |
|---|---|
POST /api/v1/documents | Reads one file. Send a document. |
GET /api/v1/documents | Lists stored documents, newest first. List documents. |
GET /api/v1/documents/{id} | Returns one document in any state. Get a document. |
DELETE /api/v1/documents/{id} | Deletes a stored document now. Delete a document. |
GET /api/v1/documents/{id}/file | Downloads the original of a collection upload. Download the original file. |
Every request takes Authorization: Bearer sb_live_... or sb_test_.... A key sees only documents of its own mode. Every response carries Cache-Control: no-store. A method a path does not support returns 405 method_not_allowed with an Allow header.
OpenAPI 3.1: statementbear.com/openapi.json describes every endpoint, schema, error and webhook. Import it into an API client, or generate a typed client from it.
Send a document#
/api/v1/documentsReads one bank or credit card statement and returns it as a document. Up to 50MB. Up to 60 pages synchronously, or 500 with async.
Request headers#
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer sb_live_..., or Bearer sb_test_... for a fixture. See Authentication. |
Content-Type | Yes | The file's own type for a raw body, such as application/pdf, image/jpeg or text/csv, or multipart/form-data. See Files you can send. |
Idempotency-Key | Recommended | One unique string per document, reused by every retry. See Idempotency and retries. |
X-Filename | No | The file's name, for a raw body. Comes back as filename. |
X-Test-Scenario | No | Test keys only. Picks which fixture or error comes back. A live key returns 400 test_scenario_on_live_key. See Test mode. |
Content-Length | Yes | The body's size in bytes. HTTP clients send it for a file. Without it the response is 411 length_required; an oversized file is refused before the upload finishes. |
Query parameters#
| Parameter | Value |
|---|---|
async | true answers 202 at once; the result arrives by webhook or GET. See Async reads. |
format | json (the default) returns a document object. csv returns the rows as CSV, qbo a QuickBooks Web Connect file, ofx an OFX 1.02 file for Quicken, Xero and GnuCash, and qif a QIF file. Synchronous only: with async it returns 400 format_requires_sync. |
metadata | A JSON object of strings, URL-encoded, for a raw body. A multipart metadata part takes precedence. |
A CSV, QBO, OFX or QIF response holds every account in the document, signs amounts (money in positive, money out negative) and gives each transaction an id that stays the same if you request the document again. It carries no verification or authenticity: request json when you need them. Errors are JSON in every format. Billing is the same in every format.
Request body#
- Raw body. The file's bytes, with its
Content-Type. - Multipart.
multipart/form-datawith the file in a part namedfile. Optional parts:passwordfor a protected PDF,metadataas a JSON string, andasyncastrue. Other parts are ignored.
The file type is read from the file's own bytes. A file the API does not read returns 415 unsupported_media_type.
Response headers#
| Header | On | Meaning |
|---|---|---|
X-Billable-Pages | Every response carrying a document | Pages billed for this document. 0 on a test key and when the pages came from your free pages. On a 202, what will be billed if the read succeeds. |
Location | 202 | The document's URL, /api/v1/documents/{id}. |
Idempotent-Replayed | Replays | true when the body is a stored document. |
X-Document-Id | 200 with format other than json | The document's id, since the file does not carry it. |
Allow | 405 | The methods the path supports. |
Cache-Control | Every response | no-store. |
Responses#
| Status | Body | Billable |
|---|---|---|
200 | A document with status: "succeeded", or the file format asked for. A replayed async document can be failed. | Yes, by pages, unless livemode is false |
202 | With async: a document with status: "processing". Also a replay of one still being read. | When it succeeds |
400 | empty_body, missing_file, invalid_body, invalid_metadata, unknown_format, format_requires_sync, test_scenario_on_live_key or unknown_test_scenario. | No |
401 | missing_key or invalid_key. | No |
402 | free_pages_exhausted, not_enough_free_pages, monthly_cap_reached or canceled, with pages. | No |
409 | idempotency_key_in_use, idempotency_key_not_replayable with reason and documentId, or document_processing. | No |
411 | length_required. | No |
413 | file_too_large, or too_many_pages with pages and limit. | No |
415 | unsupported_media_type. | No |
422 | not_a_bank_statement, password_required or incorrect_password. | No |
429 | too_many_concurrent_requests, or too_many_test_requests on a test key. | No |
500 | parse_failed. No free pages are spent. | No |
{ "id": "doc_5f2a9c4b1e77d0a3c8b6e412", "object": "document", "status": "succeeded", "error": null, "filename": "monzo-march-2026.pdf", "pages": 3, "metadata": { "applicationId": "app_8841" }, "collection": null, "livemode": true, "created": 1785372094, "issuer": { "name": "Monzo", "domain": "monzo.com" }, "currency": "GBP", "period": { "year": 2026, "month": 3 }, "accounts": [ { "type": "bank", "last4": "4412", "name": null, "currency": "GBP", "period": { "year": 2026, "month": 3 }, "primary": true, "totals": { "credits": 3240.00, "debits": 2841.55 }, "statedTotals": { "credits": 3240.00, "debits": 2841.55 }, "openingBalance": 1204.11, "closingBalance": 1602.56, "months": [ { "month": "2026-03", "credits": 3240.00, "debits": 2841.55 } ], "transactions": [ { "date": "2026-03-04", "description": "TESCO STORES 3412", "payee": "Tesco", "amount": 42.10, "direction": "debit", "category": "groceries" } ] } ], "verification": { "reconciled": true, "issues": [] }, "recurring": [ { "payee": "Spotify", "category": "subscriptions", "amount": 11.99, "cadence": "monthly", "occurrences": 1, "lastDate": "2026-03-12", "account": 0 } ], "authenticity": { "risk": "low", "signals": [], "producer": "Monzo Statements", "createdAt": "2026-04-01T06:02:11.000Z", "modifiedAt": "2026-04-01T06:02:11.000Z" }, "usage": { "pages": 3, "billablePages": 3 } }
{ "error": { "code": "not_a_bank_statement", "message": "This document does not look like a bank or card statement.", "documentId": "doc_5f2a9c4b1e77d0a3c8b6e412" } }
List documents#
/api/v1/documentsStored documents of the key's mode, newest first, in every state. Documents leave the list when your retention period ends or when you delete them.
| Parameter | Value |
|---|---|
limit | 1 to 100. Default 20. |
starting_after | A document id. Returns the documents created before it. Pass the last id of a page to get the next. An id that names no document returns 400 invalid_starting_after. |
collection | A col_ id. Only documents uploaded through it. An unknown id returns 404 collection_not_found. |
status | processing, succeeded or failed. Anything else returns 400 invalid_status. |
{ "object": "list", "data": [ { "id": "doc_5f2a9c4b1e77d0a3c8b6e412", "object": "document", "status": "succeeded", ... }, { "id": "doc_8c1d40e97a2b5f3e6d0c9a71", "object": "document", "status": "processing", ... } ], "hasMore": true }
Each entry is a whole document. hasMore is true when there are more after this page.
Get a document#
/api/v1/documents/{id}The document in whatever state it is in, with X-Billable-Pages. Poll this after an async 202 until status is succeeded or failed. An id that is not on your account, in your key's mode, returns 404 document_not_found.
{ "id": "doc_8c1d40e97a2b5f3e6d0c9a71", "object": "document", "livemode": true, "created": 1785372094, "status": "processing", "error": null, "filename": "hsbc-2025.pdf", "pages": 84, "metadata": {}, "collection": null, "issuer": null, "currency": null, "period": null, "accounts": [], "recurring": [], "verification": null, "authenticity": null, "usage": { "pages": 84, "billablePages": 84 } }
{ "id": "doc_8c1d40e97a2b5f3e6d0c9a71", "object": "document", "livemode": true, "created": 1785372094, "status": "failed", "error": { "code": "not_a_bank_statement", "message": "This document does not look like a bank or card statement." }, "filename": "hsbc-2025.pdf", "pages": 84, "metadata": {}, "collection": null, "issuer": null, "currency": null, "period": null, "accounts": [], "recurring": [], "verification": null, "authenticity": null, "usage": { "pages": 84, "billablePages": 0 } }
Delete a document#
/api/v1/documents/{id}Deletes the stored result, and the original file of a collection upload, now. It cannot be undone. The usage entry in Logs stays: it holds the page count and status your invoice is explained from, and no transactions.
{ "id": "doc_5f2a9c4b1e77d0a3c8b6e412", "object": "document", "deleted": true }
A document still being read returns 409 document_processing. Delete it once it has finished.
Download the original file#
/api/v1/documents/{id}/fileThe file exactly as the applicant uploaded it, for a document that came through a collection. Content-Disposition carries its filename and X-Document-Id its document. A document you sent directly has no stored file and returns 404 file_not_kept.
Versioning#
The version is in the path. Anything that would break code written against v1 ships as v2 at a new path, with v1 still answering, and we email the address on your account first.
| Ships as a new version | Can happen in v1 |
|---|---|
| Removing or renaming a field. | Adding an optional field. Parse leniently and ignore what you do not recognise. |
| Changing a field's type or meaning, including the units of an amount. | Adding an error code under a status you already handle, or an authenticity signal code. |
| Adding a required request header or parameter. | Rewording an error or signal message. |
| Changing which status code a failure returns. | Improving extraction accuracy, which changes the rows a given file returns. |