Skip to content
DocsAPI reference

The document object

What POST, GET and every document webhook return. Fields are never removed or changed in meaning inside v1.

A read document
{
  "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 }
}

States#

statusRead fieldserror
processingissuer, currency, period, verification and authenticity are null; accounts and recurring are empty.null
succeededEvery field is filled.null
failedAs processing.{ code, message }

id, object, livemode, created, filename, pages, metadata, collection and usage are set in every state.

Fields#

Hover or tap a field name for more detail.

idstring
Our id for this document: doc_ followed by 24 hex characters.
object"document"
Always document. Present so responses are discriminable.
status"processing" | "succeeded" | "failed"
Whether the read is done. A synchronous 200 is always succeeded.
errorobject | null
{ code, message } when status is failed. Null otherwise.
filenamestring | null
The file's name, from the multipart part or X-Filename.
pagesnumber
Pages in the file, as billed.
metadataobject
Your own key-value pairs, echoed back. {} when none were sent.
collectionstring | null
The col_ id the file was uploaded through. Null for a direct upload.
livemodeboolean
False when the document came from a test key.
creatednumber
When the document was received. Unix seconds.
issuerobject | null
The bank as printed, plus its domain for logo lookups.
currencystring | null
ISO 4217. The primary account's currency.
periodobject | null
The month the document covers: { year, month } with month 1-12.
accountsarray
One entry per account printed in the file. Usually one.
accounts[].type"bank" | "credit_card"
bank covers any deposit account: current, checking, savings.
accounts[].last4string | null
Last four of the account or card number, when it is printed.
accounts[].namestring | null
The account's own name, e.g. "360 Performance Savings".
accounts[].currencystring
ISO 4217. The account's amounts and balances are in this currency.
accounts[].periodobject
The month this account's statement is dated.
accounts[].primaryboolean
The account the issuer printed first. Exactly one per document.
accounts[].totalsobject
Our sum of the rows: { credits, debits }, both positive.
accounts[].statedTotalsobject | null
What the statement itself prints, exactly as printed.
accounts[].openingBalancenumber | null
Opening balance, when the issuer prints one.
accounts[].closingBalancenumber | null
Closing balance, when the issuer prints one.
accounts[].monthsarray
Money in and out per calendar month: { month, credits, debits }.
transactions[].datestring
YYYY-MM-DD. The date printed against the row.
transactions[].descriptionstring
The payee line as printed. Not normalised.
transactions[].payeestring | null
Who was paid, or who paid in, as a person would name them.
transactions[].amountnumber
Always positive. direction carries the sign.
transactions[].direction"credit" | "debit"
Read from the document, never from the payee name.
transactions[].categorystring
One of a fixed set. A hint for a first cut at spending mix.
verificationobject | null
Our check of the extraction against the document.
verification.issuesstring[]
What did not add up. Often empty.
recurringarray
Payments that repeat across the rows, and known subscriptions seen once.
recurring[].payeestring
Who is paid, as a person would name them.
recurring[].amountnumber
The typical amount, positive, in the account's currency.
recurring[].cadence"weekly" | "biweekly" | "monthly" | "quarterly" | "yearly" | null
How often it is paid.
recurring[].occurrencesnumber
How many times it appears in this document.
recurring[].lastDatestring
YYYY-MM-DD of the most recent payment.
recurring[].accountnumber
Index into accounts of the account that pays it.
authenticityobject | null
Signs that the file was edited or sent before. Null until the read succeeds.
authenticity.risk"low" | "medium" | "high"
high when the file's history and its figures both point at an edit.
authenticity.signalsarray
{ code, message } per signal found. Often empty.
authenticity.producerstring | null
The program the file says made it, as the PDF records it.
usageobject
{ pages, billablePages }: pages read, and how many of them are billed.

Guarantees#

  • livemode is true on a read document and false on a fixture from a test key.
  • amount is always positive. direction carries the sign.
  • Exactly one account has primary: true.
  • totals always agrees with the transactions in the same response, and months adds up to totals.
  • period.month is 1-12.
  • date is YYYY-MM-DD; months[].month is YYYY-MM.
  • usage.billablePages is never more than usage.pages.

Not included#

  • Scores, insights and affordability verdicts.
  • Merchant ids. payee is a readable name; description is the line as printed.
  • Balances on secondary accounts. Each is still checked against its own printed balances, and verification.issues names it when it does not reconcile.
  • Anything about the person whose statement it is, beyond what the document prints.
Something wrong or missing on this page? [email protected]