Skip to content
DocsAPI reference

Documents

Send a statement, list what was read, fetch one result, delete it, and download a collection upload's original file.

Method and pathDoes
POST /api/v1/documentsReads one file. Send a document.
GET /api/v1/documentsLists 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}/fileDownloads 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#

POST/api/v1/documents

Reads 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#

HeaderRequiredValue
AuthorizationYesBearer sb_live_..., or Bearer sb_test_... for a fixture. See Authentication.
Content-TypeYesThe 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-KeyRecommendedOne unique string per document, reused by every retry. See Idempotency and retries.
X-FilenameNoThe file's name, for a raw body. Comes back as filename.
X-Test-ScenarioNoTest keys only. Picks which fixture or error comes back. A live key returns 400 test_scenario_on_live_key. See Test mode.
Content-LengthYesThe 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#

ParameterValue
asynctrue answers 202 at once; the result arrives by webhook or GET. See Async reads.
formatjson (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.
metadataA 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-data with the file in a part named file. Optional parts: password for a protected PDF, metadata as a JSON string, and async as true. 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.

curl -X POST https://statementbear.com/api/v1/documents \
  -H "Authorization: Bearer $STATEMENTBEAR_KEY" \
  -H "Content-Type: application/pdf" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @statement.pdf
curl -X POST https://statementbear.com/api/v1/documents \
  -H "Authorization: Bearer $STATEMENTBEAR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F file=@statement.pdf \
  -F password=01011990 \
  -F 'metadata={"applicationId":"app_8841"}'

Response headers#

HeaderOnMeaning
X-Billable-PagesEvery response carrying a documentPages 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.
Location202The document's URL, /api/v1/documents/{id}.
Idempotent-ReplayedReplaystrue when the body is a stored document.
X-Document-Id200 with format other than jsonThe document's id, since the file does not carry it.
Allow405The methods the path supports.
Cache-ControlEvery responseno-store.

Responses#

StatusBodyBillable
200A document with status: "succeeded", or the file format asked for. A replayed async document can be failed.Yes, by pages, unless livemode is false
202With async: a document with status: "processing". Also a replay of one still being read.When it succeeds
400empty_body, missing_file, invalid_body, invalid_metadata, unknown_format, format_requires_sync, test_scenario_on_live_key or unknown_test_scenario.No
401missing_key or invalid_key.No
402free_pages_exhausted, not_enough_free_pages, monthly_cap_reached or canceled, with pages.No
409idempotency_key_in_use, idempotency_key_not_replayable with reason and documentId, or document_processing.No
411length_required.No
413file_too_large, or too_many_pages with pages and limit.No
415unsupported_media_type.No
422not_a_bank_statement, password_required or incorrect_password.No
429too_many_concurrent_requests, or too_many_test_requests on a test key.No
500parse_failed. No free pages are spent.No
200 OK
{
  "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 }
}
422 Unprocessable
{
  "error": {
    "code": "not_a_bank_statement",
    "message": "This document does not look like a bank or card statement.",
    "documentId": "doc_5f2a9c4b1e77d0a3c8b6e412"
  }
}

List documents#

GET/api/v1/documents

Stored 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.

ParameterValue
limit1 to 100. Default 20.
starting_afterA 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.
collectionA col_ id. Only documents uploaded through it. An unknown id returns 404 collection_not_found.
statusprocessing, succeeded or failed. Anything else returns 400 invalid_status.
200 OK
{
  "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#

GET/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.

200 OK, still processing
{
  "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 }
}
200 OK, failed
{
  "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#

DELETE/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.

200 OK
{ "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#

GET/api/v1/documents/{id}/file

The 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 versionCan 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.
Something wrong or missing on this page? [email protected]