The document object
What POST, GET and every document webhook return. Fields are never removed or changed in meaning inside v1.
{ "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#
status | Read fields | error |
|---|---|---|
processing | issuer, currency, period, verification and authenticity are null; accounts and recurring are empty. | null |
succeeded | Every field is filled. | null |
failed | As 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#
livemodeistrueon a read document andfalseon a fixture from a test key.amountis always positive.directioncarries the sign.- Exactly one account has
primary: true. totalsalways agrees with thetransactionsin the same response, andmonthsadds up tototals.period.monthis 1-12.dateisYYYY-MM-DD;months[].monthisYYYY-MM.usage.billablePagesis never more thanusage.pages.
Not included#
- Scores, insights and affordability verdicts.
- Merchant ids.
payeeis a readable name;descriptionis the line as printed. - Balances on secondary accounts. Each is still checked against its own printed balances, and
verification.issuesnames 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]