Skip to content
DocsGet started

Quickstart

From signing up to parsed JSON in under two minutes.

1. Create a key#

Sign in to the console with your email and create your account. That issues a live key and a test key. No payment method is needed: the first 200 pages are free. The live key is shown once, so copy it into your secret store now. The test key stays on the API keys page.

2. Send a statement#

POST the file as a raw body with its Content-Type (application/pdf for a PDF), or as multipart/form-data with a part named file. Up to 50MB and 60 pages in one request. A read takes 10 to 40 seconds, so set a client timeout of at least 180 seconds.

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

Photos and CSV, OFX or QIF exports go the same way. See Files you can send. For a file over 60 pages, up to 500, add ?async=true. See Async reads.

3. Read the response#

A success is a document object with status: "succeeded". Every account in the file is in accounts, with its rows inside it. amount is always positive and direction carries the sign.

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 }
}

4. Check the response#

  1. Only count credits as income on `type: "bank"` accounts. A credit card's credits are the monthly repayment and merchant refunds. See Amounts and directions.
  2. Check `verification.reconciled`. When it is false, send the document to manual review instead of using the totals. See Verification.
  3. Check `authenticity.risk`. When it is high, put the file in front of a person before relying on it. See Authenticity signals.
// Credit card credits are repayments and refunds. Only count
// credits on bank accounts.
const income = doc.accounts
  .filter((a) => a.type === "bank")
  .reduce((sum, a) => sum + a.totals.credits, 0);

// Send anything that did not reconcile, or looks altered, to a person.
if (!doc.verification.reconciled || doc.authenticity.risk === "high") {
  await queueForManualReview(doc.id, [
    ...doc.verification.issues,
    ...doc.authenticity.signals.map((s) => s.message),
  ]);
}

5. Make retries safe#

Send an Idempotency-Key with every request: one unique string per document, reused by every attempt at that document. A repeat of a successful call returns the stored document instead of reading the file again. See Idempotency and retries.

Next#

Something wrong or missing on this page? [email protected]