{"openapi":"3.1.0","info":{"title":"JAG Finance API","version":"1.0.0","description":"The JAG Finance API reads and changes your own data with an API key you create in Settings → API keys.\n\n**Authentication.** Send the key as `Authorization: Bearer sk_…` or as `x-api-key: sk_…`. Each key holds scopes of the form `area:read`, `area:write` or `area:delete`; a call outside them gets 403 with the scope it needed.\n\n**Money.** Every amount in a response is an integer in minor units (pence) in a field ending `Minor`, with a ready-to-show twin ending `Display` (for example `-£12.50`). Requests only take the `…Minor` form.\n\n**Dates.** A calendar day is `YYYY-MM-DD` in UK time (Europe/London). An instant is ISO 8601 in UTC.\n\n**Paging.** Lists answer `{ \"data\": [...], \"page\": { \"nextCursor\", \"hasMore\" } }`. Send `nextCursor` back as `cursor` for the next page.\n\n**Errors.** Every error is `{ \"error\": { \"code\", \"message\", \"details?\", \"requestId\" } }` with a stable `code`. Quote the request id (also in the `X-Request-Id` header) when asking for help.\n\n**Writes.** Send an `Idempotency-Key` to make a write safe to retry, and `If-Match` with an item's `version` to avoid overwriting a newer change.\n\n**Rate limits.** 1,000 requests per hour and 120 per minute per key by default. `RateLimit-*` headers show what is left; a 429 carries `Retry-After`."},"servers":[{"url":"https://finance.jagwebsites.xyz/api/v1"}],"tags":[{"name":"meta"},{"name":"documents"},{"name":"accounts"},{"name":"transactions"},{"name":"categories"},{"name":"payees"},{"name":"tags"},{"name":"bills"},{"name":"budgets"},{"name":"goals"},{"name":"insights"},{"name":"search"},{"name":"inbox"}],"paths":{"/me":{"get":{"operationId":"getMe","tags":["meta"],"summary":"The key making the request","description":"Who the key belongs to and what it may do. Any valid key can call it, so it is the quickest way to check a key works. `accountLimit` lists the accounts a key limited to some accounts may use (null for every account).\n\nAny valid API key can call this.","x-required-scope":null,"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string","description":"The key id (not the secret)."},"name":{"description":"The name you gave the key.","type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"},"description":"What the key may do, such as `accounts:read`."},"createdAt":{"description":"When the key was created, ISO 8601 in UTC.","type":["string","null"]},"expiresAt":{"description":"When the key stops working, ISO 8601 in UTC; null if it never does.","type":["string","null"]},"lastUsedAt":{"description":"When the key was last used, ISO 8601 in UTC; null if never.","type":["string","null"]}},"required":["id","name","scopes","createdAt","expiresAt","lastUsedAt"],"description":"The key making the request.","additionalProperties":false},"user":{"type":"object","properties":{"id":{"type":"string","description":"The id of the person the key belongs to."},"name":{"description":"Their name.","type":["string","null"]}},"required":["id","name"],"description":"Who the key belongs to.","additionalProperties":false},"rateLimit":{"type":"object","properties":{"perMinute":{"type":"integer","description":"Requests allowed per minute."},"window":{"anyOf":[{"type":"object","properties":{"limit":{"type":"integer","description":"Requests allowed in the window."},"seconds":{"type":"integer","description":"Length of the window in seconds."}},"required":["limit","seconds"],"additionalProperties":false},{"type":"null"}],"description":"The longer limit, such as 1,000 an hour; null when rate limiting is off for the key."}},"required":["perMinute","window"],"description":"How many requests the key may make.","additionalProperties":false},"accountLimit":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The account id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false}},{"type":"null"}],"description":"The financial accounts the key is limited to, or null when it may use every account."},"connection":{"description":"Only when a connected app calls with its OAuth access token: the connection it acts for. `key` then describes that connection.","anyOf":[{"type":"object","properties":{"grantId":{"type":"string","description":"The connection (grant) the token acts for."},"clientId":{"type":"string","description":"The connected app, such as `jag-work`."},"scopes":{"type":"array","items":{"type":"string"},"description":"What the app may do."},"accountIds":{"type":"array","items":{"type":"string"},"description":"The accounts the person allowed it to see."}},"required":["grantId","clientId","scopes","accountIds"],"additionalProperties":false},{"type":"null"}]}},"required":["key","user","rateLimit","accountLimit"],"additionalProperties":false}}},"example":{"data":{"key":{"id":"key_id","name":"Spending widget","scopes":["accounts:read","insights:read"],"createdAt":"2026-10-26T09:00:00.000Z","expiresAt":null,"lastUsedAt":"2026-10-26T09:05:00.000Z"},"user":{"id":"user_id","name":"Alex"},"rateLimit":{"perMinute":120,"window":{"limit":1000,"seconds":3600}},"accountLimit":null}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/connection":{"get":{"operationId":"getConnection","tags":["meta"],"summary":"The app’s connection","description":"For a connected app (OAuth token): what the person allowed it, the accounts it can see and its webhook. A key gets 403.\n\nAny valid API key can call this.","x-required-scope":null,"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"grantId":{"type":"string","description":"The connection."},"app":{"type":"object","properties":{"clientId":{"type":"string","description":"Its client id, such as `jag-work`."},"name":{"type":"string","description":"Its name."}},"required":["clientId","name"],"description":"The app it is for.","additionalProperties":false},"scopes":{"type":"array","items":{"type":"string"},"description":"What the app may do."},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The account id."},"name":{"type":"string","description":"Its name."},"institution":{"type":"string","description":"The bank."},"mask":{"description":"The last four digits, when known.","type":["string","null"]},"closed":{"type":"boolean","description":"True for a closed account."}},"required":["id","name","institution","mask","closed"],"additionalProperties":false},"description":"The accounts the person allowed it to see."},"webhook":{"anyOf":[{"type":"object","properties":{"url":{"description":"Where events go.","type":["string","null"]},"events":{"type":"array","items":{"type":"string"},"description":"What it is told about."},"status":{"type":"string","enum":["healthy","failing","off"],"description":"`failing` while deliveries fail; `off` once switched off for failing."},"lastSuccessAt":{"description":"The last delivery that worked, ISO 8601 in UTC.","type":["string","null"]},"lastFailureAt":{"description":"The last delivery that failed, ISO 8601 in UTC.","type":["string","null"]}},"required":["url","events","status","lastSuccessAt","lastFailureAt"],"additionalProperties":false},{"type":"null"}],"description":"Its webhook, if it has set one."},"createdAt":{"description":"When it was connected.","type":["string","null"]},"changedAt":{"description":"When the accounts or scopes last changed.","type":["string","null"]}},"required":["grantId","app","scopes","accounts","webhook","createdAt","changedAt"],"additionalProperties":false}}},"example":{"data":{"grantId":"grant_id","app":{"clientId":"jag-work","name":"JAG Work"},"scopes":["transactions:read","accounts:read","documents:read","documents:upload"],"accounts":[{"id":"account_id","name":"Current account","institution":"Monzo","mask":"0192","closed":false}],"webhook":{"url":"https://work.example.com/api/finance/webhook","events":["transaction.created","document.attached"],"status":"healthy","lastSuccessAt":"2026-11-03T08:31:00.000Z","lastFailureAt":null},"createdAt":"2026-09-02T10:02:00.000Z","changedAt":"2026-09-02T10:02:00.000Z"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/connection/webhook":{"put":{"operationId":"putConnectionWebhook","tags":["meta"],"summary":"Set the app’s webhook","description":"Makes the connection’s webhook, or moves it to a new address. Every call answers with a new signing secret (`whsec_…`), shown only here. It is told about transaction.created, transaction.updated, transaction.deleted, document.attached, document.detached, on the allowed accounts only, with ids and no figures, and `connection.revoked` once when access ends.\n\nAny valid API key can call this.","x-required-scope":null,"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"Where to send events: an https address."}},"required":["url"],"additionalProperties":false},"example":{"url":"https://work.example.com/api/finance/webhook"}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The webhook."},"url":{"description":"Where events go.","type":["string","null"]},"events":{"type":"array","items":{"type":"string"},"description":"What it is told about."},"secret":{"type":"string","description":"Signs each request (`JAG-Signature`). Store it; it is not shown again."}},"required":["id","url","events","secret"],"additionalProperties":false}}},"example":{"data":{"id":"endpoint_id","url":"https://work.example.com/api/finance/webhook","events":["transaction.created","transaction.updated","transaction.deleted","document.attached","document.detached"],"secret":"whsec_…"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"deleteConnectionWebhook","tags":["meta"],"summary":"Remove the app’s webhook","description":"Stops sending events to the connection’s webhook.\n\nAny valid API key can call this.","x-required-scope":null,"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"responses":{"204":{"description":"Done. There is no body.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/connection/payslips":{"post":{"operationId":"postConnectionPayslips","tags":["documents"],"summary":"Add a payslip to a payment","description":"Uploads a payslip (a `multipart/form-data` form with the file in `file`, at most 4 MB) and attaches it to `transactionId`, a payment the app can see. It is filed as a payslip, so JAG Finance reads it and Itemise salary can run. Answers 201 with the document; when the same file is already a document, that one is attached instead (200).\n\nNeeds the `documents:upload` scope.","x-required-scope":"documents:upload","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"transactionId","in":"query","required":true,"description":"The payment (income) to attach the payslip to.","schema":{"type":"string","minLength":1,"maxLength":64},"example":"txn_1"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["added","existing"],"description":"`added` for a new document; `existing` when the same file was already one."},"documentId":{"type":"string","description":"The payslip."},"transactionId":{"type":"string","description":"The payment it is attached to."}},"required":["status","documentId","transactionId"],"additionalProperties":false}}},"example":{"data":{"status":"added","documentId":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","transactionId":"txn_1"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/openapi.json":{"get":{"operationId":"getOpenapiJson","tags":["meta"],"summary":"The OpenAPI 3.1 description of this API","description":"Every endpoint with its scope, inputs and outputs, generated from the code that serves them. Needs no key and holds no data, so tools can fetch it freely.\n\nNo API key needed.","security":[],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"openapi":{"type":"string","description":"The OpenAPI version, `3.1.0`."},"info":{"type":"object","properties":{"title":{"type":"string","description":"The name of the API."},"version":{"type":"string","description":"The version of the API."}},"required":["title","version"],"additionalProperties":{},"description":"About the API."},"servers":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"The base address of the API."}},"required":["url"],"additionalProperties":false},"description":"Where the API is served."},"paths":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Every endpoint, by path then method."},"components":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Shared schemas, parameters and responses the endpoints refer to."}},"required":["openapi","info","servers","paths","components"],"additionalProperties":{}},"example":{"openapi":"3.1.0","info":{"title":"JAG Finance API","version":"1.0.0"},"servers":[{"url":"https://finance.example.com/api/v1"}],"paths":{"/me":{"get":{"operationId":"getMe"}}},"components":{}}}}}}}},"/client.ts":{"get":{"operationId":"getClientTs","tags":["meta"],"summary":"A ready-made TypeScript client for this API","description":"One self-contained TypeScript file with a type for every request and answer and a method for every endpoint (`createJagFinanceClient({ apiKey })`), generated from the same code as the OpenAPI file. Save it into your project (`curl -o jag-finance.ts …/client.ts`) and import it: no package to install. Needs no key and holds no data.\n\nNo API key needed.","security":[],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"text/plain; charset=utf-8":{"schema":{"type":"string"},"example":"export function createJagFinanceClient(options: JagFinanceClientOptions) {\n  // …one method per endpoint, such as getTransactions({ query })\n}"}}}}}},"/accounts":{"get":{"operationId":"getAccounts","tags":["accounts"],"summary":"List accounts","description":"Every financial account with its current balance (the figure the Accounts page shows: lines dated in the future count once their day comes). Closed accounts are hidden unless `closed=include` or `closed=only`. Each account lists its `targets`, the payment sources (the account itself, cards, pots) that transactions are posted against. A credit account's balance is negative when money is owed. To keep a copy in step, send `updatedSince`: only accounts edited since then come back, closed ones included and flagged. An account counts as edited when the account or one of its targets changes (renamed, closed, limit, a card added); `balance` moves with your transactions without that, so refresh the balances you show. A connected app gets its accounts without `balance` or `creditLimit`.\n\nNeeds the `accounts:read` scope.","x-required-scope":"accounts:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"closed","in":"query","required":false,"description":"Closed accounts: `exclude` (default), `include` or `only`. With `updatedSince` the default is `include`, so a closing shows.","schema":{"type":"string","enum":["exclude","include","only"]}},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The account id."},"name":{"type":"string","description":"The account name."},"institution":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The bank or provider it is held with.","additionalProperties":false},"kind":{"type":"string","enum":["current","savings","credit","cash"],"description":"What sort of account it is."},"subtype":{"anyOf":[{"type":"string","enum":["savings_pot"]},{"type":"null"}],"description":"`savings_pot` for a pot inside another account; otherwise null."},"currency":{"type":"string","description":"The account currency, such as GBP."},"closed":{"type":"boolean","description":"True once the account has been closed."},"keepAside":{"type":"boolean","description":"Left out of planning cash (Safe to spend, Forecast, Runway), but still in balances."},"statementDay":{"type":"integer","description":"The day of the month its statement cycle starts (1 to 31). Only means something when `statementSchedule` is `monthly`."},"statementSchedule":{"type":"string","enum":["monthly","around","none"],"description":"`monthly`: a statement each cycle from `statementDay`. `around`: monthly, each statement starting up to 3 days either side of `statementDay`. `none` (By statement, the default for new accounts): no fixed day, each statement keeps its own printed dates."},"dateOpened":{"description":"The day it was opened, YYYY-MM-DD.","type":["string","null"]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"Its name."},"kind":{"anyOf":[{"type":"string","enum":["direct","debit_card","credit_card","virtual_card","savings_pot","cash"]},{"type":"null"}],"description":"What this payment source is. `direct` is the account itself."},"lastFour":{"description":"The last four digits of the card, when it has them.","type":["string","null"]},"closed":{"type":"boolean","description":"True once it has been closed."}},"required":["id","name","kind","lastFour","closed"],"additionalProperties":false},"description":"The ways money is paid in or out: the account itself, its cards, pots and so on."},"version":{"type":"string","description":"Send as `If-Match` when editing the account."},"balanceMinor":{"type":"integer","description":"The current balance in pence. Negative when money is owed."},"balanceDisplay":{"type":"string","description":"The current balance ready to show, such as £1,250.00."},"creditLimitMinor":{"description":"The credit limit in pence; null when there is none. Negative when money is owed.","type":["integer","null"]},"creditLimitDisplay":{"description":"The credit limit ready to show, such as £1,250.00.","type":["string","null"]}},"required":["id","name","institution","kind","subtype","currency","closed","keepAside","statementDay","statementSchedule","dateOpened","targets","version","balanceMinor","balanceDisplay","creditLimitMinor","creditLimitDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"acc_current","name":"Everyday","institution":{"id":"inst_bank","name":"Example Bank"},"kind":"current","subtype":null,"currency":"GBP","closed":false,"keepAside":false,"balanceMinor":123450,"balanceDisplay":"£1,234.50","creditLimitMinor":null,"creditLimitDisplay":null,"statementDay":1,"statementSchedule":"none","dateOpened":"2024-03-14","targets":[{"id":"src_direct","name":"Everyday","kind":"direct","lastFour":null,"closed":false},{"id":"src_card","name":"Everyday debit card","kind":"debit_card","lastFour":"4242","closed":false}],"version":"1792000000000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/accounts/{id}":{"get":{"operationId":"getAccountsById","tags":["accounts"],"summary":"Get an account","description":"One account, as in the list, plus `latestBalanceCheck`: the most recent check of the account against what the provider showed, or null when there are none. `differenceMinor` is the provider balance minus the ledger balance at that moment.\n\nNeeds the `accounts:read` scope.","x-required-scope":"accounts:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The account id.","schema":{"type":"string","minLength":1},"example":"acc_current"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The account id."},"name":{"type":"string","description":"The account name."},"institution":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The bank or provider it is held with.","additionalProperties":false},"kind":{"type":"string","enum":["current","savings","credit","cash"],"description":"What sort of account it is."},"subtype":{"anyOf":[{"type":"string","enum":["savings_pot"]},{"type":"null"}],"description":"`savings_pot` for a pot inside another account; otherwise null."},"currency":{"type":"string","description":"The account currency, such as GBP."},"closed":{"type":"boolean","description":"True once the account has been closed."},"keepAside":{"type":"boolean","description":"Left out of planning cash (Safe to spend, Forecast, Runway), but still in balances."},"statementDay":{"type":"integer","description":"The day of the month its statement cycle starts (1 to 31). Only means something when `statementSchedule` is `monthly`."},"statementSchedule":{"type":"string","enum":["monthly","around","none"],"description":"`monthly`: a statement each cycle from `statementDay`. `around`: monthly, each statement starting up to 3 days either side of `statementDay`. `none` (By statement, the default for new accounts): no fixed day, each statement keeps its own printed dates."},"dateOpened":{"description":"The day it was opened, YYYY-MM-DD.","type":["string","null"]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"Its name."},"kind":{"anyOf":[{"type":"string","enum":["direct","debit_card","credit_card","virtual_card","savings_pot","cash"]},{"type":"null"}],"description":"What this payment source is. `direct` is the account itself."},"lastFour":{"description":"The last four digits of the card, when it has them.","type":["string","null"]},"closed":{"type":"boolean","description":"True once it has been closed."}},"required":["id","name","kind","lastFour","closed"],"additionalProperties":false},"description":"The ways money is paid in or out: the account itself, its cards, pots and so on."},"version":{"type":"string","description":"Send as `If-Match` when editing the account."},"balanceMinor":{"type":"integer","description":"The current balance in pence. Negative when money is owed."},"balanceDisplay":{"type":"string","description":"The current balance ready to show, such as £1,250.00."},"creditLimitMinor":{"description":"The credit limit in pence; null when there is none. Negative when money is owed.","type":["integer","null"]},"creditLimitDisplay":{"description":"The credit limit ready to show, such as £1,250.00.","type":["string","null"]},"latestBalanceCheck":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The balance check id."},"accountId":{"type":"string","description":"The account it was recorded against."},"observedOn":{"type":"string","description":"The UK calendar day the provider balance was read."},"observedAt":{"description":"The exact moment, when it was recorded (older checks have only the day).","type":["string","null"]},"matches":{"type":"boolean","description":"True when the provider balance equals the ledger balance."},"note":{"description":"A short note added with the check.","type":["string","null"]},"resolved":{"type":"boolean","description":"True once a difference has been marked as dealt with."},"resolvedAt":{"description":"When it was marked resolved, ISO 8601 in UTC.","type":["string","null"]},"resolutionNote":{"description":"What was done about the difference.","type":["string","null"]},"createdAt":{"description":"When the check was recorded, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when changing the check."},"observedMinor":{"type":"integer","description":"The balance the bank or provider showed in pence. Negative when money is owed."},"observedDisplay":{"type":"string","description":"The balance the bank or provider showed ready to show, such as £1,250.00."},"ledgerMinor":{"type":"integer","description":"The balance JAG Finance worked out in pence. Negative when money is owed."},"ledgerDisplay":{"type":"string","description":"The balance JAG Finance worked out ready to show, such as £1,250.00."},"differenceMinor":{"type":"integer","description":"Observed minus ledger in pence. Negative when money is owed."},"differenceDisplay":{"type":"string","description":"Observed minus ledger ready to show, such as £1,250.00."}},"required":["id","accountId","observedOn","observedAt","matches","note","resolved","resolvedAt","resolutionNote","createdAt","version","observedMinor","observedDisplay","ledgerMinor","ledgerDisplay","differenceMinor","differenceDisplay"],"additionalProperties":false},{"type":"null"}],"description":"The most recent balance check, or null when there is none."}},"required":["id","name","institution","kind","subtype","currency","closed","keepAside","statementDay","statementSchedule","dateOpened","targets","version","balanceMinor","balanceDisplay","creditLimitMinor","creditLimitDisplay","latestBalanceCheck"],"additionalProperties":false}}},"example":{"data":{"id":"acc_current","name":"Everyday","institution":{"id":"inst_bank","name":"Example Bank"},"kind":"current","subtype":null,"currency":"GBP","closed":false,"keepAside":false,"balanceMinor":123450,"balanceDisplay":"£1,234.50","creditLimitMinor":null,"creditLimitDisplay":null,"statementDay":1,"statementSchedule":"none","dateOpened":"2024-03-14","targets":[{"id":"src_direct","name":"Everyday","kind":"direct","lastFour":null,"closed":false},{"id":"src_card","name":"Everyday debit card","kind":"debit_card","lastFour":"4242","closed":false}],"version":"1792000000000","latestBalanceCheck":{"id":"chk_1","accountId":"acc_current","observedOn":"2026-10-20","observedAt":"2026-10-20T08:30:00.000Z","observedMinor":123450,"observedDisplay":"£1,234.50","ledgerMinor":123000,"ledgerDisplay":"£1,230.00","differenceMinor":450,"differenceDisplay":"£4.50","matches":false,"note":null,"resolved":false,"resolvedAt":null,"resolutionNote":null,"createdAt":"2026-10-20T08:31:00.000Z","version":"1792000000001"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"patchAccountsById","tags":["accounts"],"summary":"Rename, close or keep aside an account","description":"Changes the fields you send and leaves the rest. Closing an account hides it from the default list and from new transactions; its history stays. Send the `version` you last read as `If-Match` (or in the body): if the account has changed since, the answer is 412 `version_conflict`. The answer is the account as `GET /accounts/{id}` shows it.\n\nNeeds the `accounts:write` scope.","x-required-scope":"accounts:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The account id.","schema":{"type":"string","minLength":1},"example":"acc_current"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"A new name.","type":"string","minLength":1,"maxLength":160},"closed":{"description":"True closes the account; false reopens it. The default cash account cannot be closed.","type":"boolean"},"keepAside":{"description":"True leaves the account out of planning cash (Safe to spend, Forecast, Runway). Credit accounts cannot be kept aside.","type":"boolean"},"version":{"description":"The `version` you last read, as an alternative to the `If-Match` header.","type":"string"}},"additionalProperties":false},"example":{"name":"Everyday account","keepAside":false}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The account id."},"name":{"type":"string","description":"The account name."},"institution":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The bank or provider it is held with.","additionalProperties":false},"kind":{"type":"string","enum":["current","savings","credit","cash"],"description":"What sort of account it is."},"subtype":{"anyOf":[{"type":"string","enum":["savings_pot"]},{"type":"null"}],"description":"`savings_pot` for a pot inside another account; otherwise null."},"currency":{"type":"string","description":"The account currency, such as GBP."},"closed":{"type":"boolean","description":"True once the account has been closed."},"keepAside":{"type":"boolean","description":"Left out of planning cash (Safe to spend, Forecast, Runway), but still in balances."},"statementDay":{"type":"integer","description":"The day of the month its statement cycle starts (1 to 31). Only means something when `statementSchedule` is `monthly`."},"statementSchedule":{"type":"string","enum":["monthly","around","none"],"description":"`monthly`: a statement each cycle from `statementDay`. `around`: monthly, each statement starting up to 3 days either side of `statementDay`. `none` (By statement, the default for new accounts): no fixed day, each statement keeps its own printed dates."},"dateOpened":{"description":"The day it was opened, YYYY-MM-DD.","type":["string","null"]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"Its name."},"kind":{"anyOf":[{"type":"string","enum":["direct","debit_card","credit_card","virtual_card","savings_pot","cash"]},{"type":"null"}],"description":"What this payment source is. `direct` is the account itself."},"lastFour":{"description":"The last four digits of the card, when it has them.","type":["string","null"]},"closed":{"type":"boolean","description":"True once it has been closed."}},"required":["id","name","kind","lastFour","closed"],"additionalProperties":false},"description":"The ways money is paid in or out: the account itself, its cards, pots and so on."},"version":{"type":"string","description":"Send as `If-Match` when editing the account."},"balanceMinor":{"type":"integer","description":"The current balance in pence. Negative when money is owed."},"balanceDisplay":{"type":"string","description":"The current balance ready to show, such as £1,250.00."},"creditLimitMinor":{"description":"The credit limit in pence; null when there is none. Negative when money is owed.","type":["integer","null"]},"creditLimitDisplay":{"description":"The credit limit ready to show, such as £1,250.00.","type":["string","null"]},"latestBalanceCheck":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The balance check id."},"accountId":{"type":"string","description":"The account it was recorded against."},"observedOn":{"type":"string","description":"The UK calendar day the provider balance was read."},"observedAt":{"description":"The exact moment, when it was recorded (older checks have only the day).","type":["string","null"]},"matches":{"type":"boolean","description":"True when the provider balance equals the ledger balance."},"note":{"description":"A short note added with the check.","type":["string","null"]},"resolved":{"type":"boolean","description":"True once a difference has been marked as dealt with."},"resolvedAt":{"description":"When it was marked resolved, ISO 8601 in UTC.","type":["string","null"]},"resolutionNote":{"description":"What was done about the difference.","type":["string","null"]},"createdAt":{"description":"When the check was recorded, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when changing the check."},"observedMinor":{"type":"integer","description":"The balance the bank or provider showed in pence. Negative when money is owed."},"observedDisplay":{"type":"string","description":"The balance the bank or provider showed ready to show, such as £1,250.00."},"ledgerMinor":{"type":"integer","description":"The balance JAG Finance worked out in pence. Negative when money is owed."},"ledgerDisplay":{"type":"string","description":"The balance JAG Finance worked out ready to show, such as £1,250.00."},"differenceMinor":{"type":"integer","description":"Observed minus ledger in pence. Negative when money is owed."},"differenceDisplay":{"type":"string","description":"Observed minus ledger ready to show, such as £1,250.00."}},"required":["id","accountId","observedOn","observedAt","matches","note","resolved","resolvedAt","resolutionNote","createdAt","version","observedMinor","observedDisplay","ledgerMinor","ledgerDisplay","differenceMinor","differenceDisplay"],"additionalProperties":false},{"type":"null"}],"description":"The most recent balance check, or null when there is none."}},"required":["id","name","institution","kind","subtype","currency","closed","keepAside","statementDay","statementSchedule","dateOpened","targets","version","balanceMinor","balanceDisplay","creditLimitMinor","creditLimitDisplay","latestBalanceCheck"],"additionalProperties":false}}},"example":{"data":{"id":"acc_current","name":"Everyday account","institution":{"id":"inst_bank","name":"Example Bank"},"kind":"current","subtype":null,"currency":"GBP","closed":false,"keepAside":false,"balanceMinor":123450,"balanceDisplay":"£1,234.50","creditLimitMinor":null,"creditLimitDisplay":null,"statementDay":1,"statementSchedule":"none","dateOpened":"2024-03-14","targets":[{"id":"src_direct","name":"Everyday","kind":"direct","lastFour":null,"closed":false},{"id":"src_card","name":"Everyday debit card","kind":"debit_card","lastFour":"4242","closed":false}],"version":"1792000000000","latestBalanceCheck":{"id":"chk_1","accountId":"acc_current","observedOn":"2026-10-20","observedAt":"2026-10-20T08:30:00.000Z","observedMinor":123450,"observedDisplay":"£1,234.50","ledgerMinor":123000,"ledgerDisplay":"£1,230.00","differenceMinor":450,"differenceDisplay":"£4.50","matches":false,"note":null,"resolved":false,"resolvedAt":null,"resolutionNote":null,"createdAt":"2026-10-20T08:31:00.000Z","version":"1792000000001"}}}}}},"400":{"description":"`validation_failed`: The body is empty, or `keepAside` is set on a credit account. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/institutions":{"get":{"operationId":"getInstitutions","tags":["accounts"],"summary":"List institutions","description":"Banks, building societies and the like that hold your accounts, with the ids of the accounts under each (open and closed). To keep a copy in step, send `updatedSince`: an institution comes back when it, or any account under it, changed since then (closed ones included and flagged).\n\nNeeds the `accounts:read` scope.","x-required-scope":"accounts:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The institution id."},"name":{"type":"string","description":"The institution name."},"closed":{"type":"boolean","description":"True once it has been closed."},"accountIds":{"type":"array","items":{"type":"string"},"description":"The ids of its accounts."}},"required":["id","name","closed","accountIds"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"inst_bank","name":"Example Bank","closed":false,"accountIds":["acc_current","acc_savings"]}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/accounts/{id}/balance-checks":{"get":{"operationId":"getAccountsByIdBalanceChecks","tags":["accounts"],"summary":"List an account's balance checks","description":"The account's most recent balance checks (up to 30), newest first. The ledger figure is recomputed on each read, so a later backdated transaction changes `ledger` and `difference` of an old check.\n\nNeeds the `accounts:read` scope.","x-required-scope":"accounts:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The account id.","schema":{"type":"string","minLength":1},"example":"acc_current"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The balance check id."},"accountId":{"type":"string","description":"The account it was recorded against."},"observedOn":{"type":"string","description":"The UK calendar day the provider balance was read."},"observedAt":{"description":"The exact moment, when it was recorded (older checks have only the day).","type":["string","null"]},"matches":{"type":"boolean","description":"True when the provider balance equals the ledger balance."},"note":{"description":"A short note added with the check.","type":["string","null"]},"resolved":{"type":"boolean","description":"True once a difference has been marked as dealt with."},"resolvedAt":{"description":"When it was marked resolved, ISO 8601 in UTC.","type":["string","null"]},"resolutionNote":{"description":"What was done about the difference.","type":["string","null"]},"createdAt":{"description":"When the check was recorded, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when changing the check."},"observedMinor":{"type":"integer","description":"The balance the bank or provider showed in pence. Negative when money is owed."},"observedDisplay":{"type":"string","description":"The balance the bank or provider showed ready to show, such as £1,250.00."},"ledgerMinor":{"type":"integer","description":"The balance JAG Finance worked out in pence. Negative when money is owed."},"ledgerDisplay":{"type":"string","description":"The balance JAG Finance worked out ready to show, such as £1,250.00."},"differenceMinor":{"type":"integer","description":"Observed minus ledger in pence. Negative when money is owed."},"differenceDisplay":{"type":"string","description":"Observed minus ledger ready to show, such as £1,250.00."}},"required":["id","accountId","observedOn","observedAt","matches","note","resolved","resolvedAt","resolutionNote","createdAt","version","observedMinor","observedDisplay","ledgerMinor","ledgerDisplay","differenceMinor","differenceDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"chk_1","accountId":"acc_current","observedOn":"2026-10-20","observedAt":"2026-10-20T08:30:00.000Z","observedMinor":123450,"observedDisplay":"£1,234.50","ledgerMinor":123000,"ledgerDisplay":"£1,230.00","differenceMinor":450,"differenceDisplay":"£4.50","matches":false,"note":null,"resolved":false,"resolvedAt":null,"resolutionNote":null,"createdAt":"2026-10-20T08:31:00.000Z","version":"1792000000001"}],"page":{"nextCursor":null,"hasMore":false}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postAccountsByIdBalanceChecks","tags":["accounts"],"summary":"Record a balance check","description":"Records what your bank or provider showed for the account, so it can be compared with the ledger. The answer includes the ledger balance at that moment and the difference. Send `observedAt` (a time) or `observedOn` (a UK day, covering the whole day); neither may be in the future. Recording a check changes no transactions.\n\nNeeds the `accounts:write` scope.","x-required-scope":"accounts:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The account id.","schema":{"type":"string","minLength":1},"example":"acc_current"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"observedMinor":{"type":"integer","minimum":-2147483647,"maximum":2147483647,"description":"The balance the bank or provider showed, in pence. Negative when money is owed."},"observedOn":{"description":"The UK day it was read, `YYYY-MM-DD`, today or earlier. Covers the whole day; prefer `observedAt` when you know the time.","type":"string"},"observedAt":{"description":"The exact moment it was read, an ISO 8601 time such as `2026-10-24T08:30:00Z`.","type":"string","format":"date-time"},"note":{"description":"A short note.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},"required":["observedMinor"],"additionalProperties":false},"example":{"observedMinor":123450,"observedAt":"2026-10-20T08:30:00Z","note":"From the app"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The balance check id."},"accountId":{"type":"string","description":"The account it was recorded against."},"observedOn":{"type":"string","description":"The UK calendar day the provider balance was read."},"observedAt":{"description":"The exact moment, when it was recorded (older checks have only the day).","type":["string","null"]},"matches":{"type":"boolean","description":"True when the provider balance equals the ledger balance."},"note":{"description":"A short note added with the check.","type":["string","null"]},"resolved":{"type":"boolean","description":"True once a difference has been marked as dealt with."},"resolvedAt":{"description":"When it was marked resolved, ISO 8601 in UTC.","type":["string","null"]},"resolutionNote":{"description":"What was done about the difference.","type":["string","null"]},"createdAt":{"description":"When the check was recorded, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when changing the check."},"observedMinor":{"type":"integer","description":"The balance the bank or provider showed in pence. Negative when money is owed."},"observedDisplay":{"type":"string","description":"The balance the bank or provider showed ready to show, such as £1,250.00."},"ledgerMinor":{"type":"integer","description":"The balance JAG Finance worked out in pence. Negative when money is owed."},"ledgerDisplay":{"type":"string","description":"The balance JAG Finance worked out ready to show, such as £1,250.00."},"differenceMinor":{"type":"integer","description":"Observed minus ledger in pence. Negative when money is owed."},"differenceDisplay":{"type":"string","description":"Observed minus ledger ready to show, such as £1,250.00."}},"required":["id","accountId","observedOn","observedAt","matches","note","resolved","resolvedAt","resolutionNote","createdAt","version","observedMinor","observedDisplay","ledgerMinor","ledgerDisplay","differenceMinor","differenceDisplay"],"additionalProperties":false}}},"example":{"data":{"id":"chk_1","accountId":"acc_current","observedOn":"2026-10-20","observedAt":"2026-10-20T08:30:00.000Z","observedMinor":123450,"observedDisplay":"£1,234.50","ledgerMinor":123000,"ledgerDisplay":"£1,230.00","differenceMinor":450,"differenceDisplay":"£4.50","matches":false,"note":null,"resolved":false,"resolvedAt":null,"resolutionNote":null,"createdAt":"2026-10-20T08:31:00.000Z","version":"1792000000001"}}}}},"400":{"description":"`validation_failed`: Neither `observedAt` nor `observedOn` is sent, or the time is in the future. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/transactions":{"get":{"operationId":"getTransactions","tags":["transactions"],"summary":"List transactions","description":"Transactions newest first, each with its lines and tags. `amount` is the net of the lines from your side: money out is negative, and a transfer nets to zero. A transaction’s `kind` is read from all of its lines (a discount line does not turn a purchase into income). `minAmountMinor` / `maxAmountMinor` compare the absolute net amount. Filters on category, payee and account match when any line matches; a parent category or payee also matches its subcategories and sub-payees. Use `version` as the If-Match value when editing. To keep a copy in step, pass `updatedSince` (the `page.asOf` of your last run) and upsert what comes back; transactions are hard-deleted, so list ids occasionally to find the missing ones.\n\nNeeds the `transactions:read` scope.","x-required-scope":"transactions:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Earliest date, inclusive. `YYYY-MM-DD` (a whole UK day) or an ISO 8601 timestamp.","schema":{"type":"string"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"Latest date, inclusive. `YYYY-MM-DD` runs to the end of that UK day; a timestamp is that instant.","schema":{"type":"string"}},{"name":"accountId","in":"query","required":false,"description":"A payment source (card, pot or account activity) id, or a financial account id for all of its sources.","schema":{"type":"string","minLength":1}},{"name":"categoryId","in":"query","required":false,"description":"Only transactions with a line in this category or any category under it (a parent category includes its subcategories, as on the Transactions page).","schema":{"type":"string","minLength":1}},{"name":"payeeId","in":"query","required":false,"description":"Only transactions with a line for this payee or any payee under it (a parent payee includes its sub-payees).","schema":{"type":"string","minLength":1}},{"name":"tagId","in":"query","required":false,"description":"Only transactions carrying this tag.","schema":{"type":"string","minLength":1}},{"name":"kind","in":"query","required":false,"description":"Expense, income or transfer, read from all of a transaction’s lines as the app does.","schema":{"type":"string","enum":["expense","income","transfer"]},"example":"expense"},{"name":"minAmountMinor","in":"query","required":false,"description":"Smallest absolute amount in pence, up to 2147483647.","schema":{"type":"integer","minimum":0,"maximum":2147483647}},{"name":"maxAmountMinor","in":"query","required":false,"description":"Largest absolute amount in pence, up to 2147483647.","schema":{"type":"integer","minimum":0,"maximum":2147483647}},{"name":"q","in":"query","required":false,"description":"Text search over the description, notes and item names, with the same AND / OR / NOT, \"quotes\" and accent folding as the Transactions page.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"hasDocuments","in":"query","required":false,"description":"`true` for transactions with documents attached, `false` for those without. Needs the `documents:read` scope and a key for all accounts.","schema":{"type":"string","enum":["0","1","true","false"]}},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check). A transaction counts as changed when its header, any of its lines or its tags were (the same stamp as `version`); deleting a tag altogether does not move the transactions that had it. Transactions are hard-deleted, so a deleted one never appears. Paging works as usual.","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"description":"`documents` adds each transaction’s attached documents (id and title). Needs the `documents:read` scope and a key for all accounts.","schema":{"type":"string","enum":["documents"]}},{"name":"limit","in":"query","required":false,"description":"Transactions per page, 1–200 (50 by default).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"example":"20"},{"name":"cursor","in":"query","required":false,"description":"`page.nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The transaction id."},"date":{"type":"string","description":"The day it happened, YYYY-MM-DD in UK time."},"at":{"type":"string","description":"The moment it happened, ISO 8601 in UTC."},"description":{"type":"string","description":"What the transaction is called."},"descriptionAuto":{"type":"boolean","description":"True when the app writes the description from the lines, and rewrites it when they change."},"notes":{"description":"Free-text notes.","type":["string","null"]},"kind":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money went out, came in, or moved between your own accounts."},"isTransfer":{"type":"boolean","description":"True for a move between your own accounts."},"isRoundUp":{"type":"boolean","description":"True for a round-up transfer into savings."},"amountMinor":{"type":"integer","description":"Net amount of all lines in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Net amount of all lines ready to show, such as -£12.50."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line id."},"account":{"type":"object","properties":{"id":{"description":"Its id; null for another account, to a key limited to some accounts.","type":["string","null"]},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account this line moves money in or out of. For a key limited to some accounts, a line on another account shows `{ \"id\": null, \"name\": \"Another account\" }`.","additionalProperties":false},"amountMinor":{"type":"integer","description":"Amount of this line in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Amount of this line ready to show, such as -£12.50."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line's category, or null when it has none."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who was paid, or null when none is set."},"itemName":{"description":"What was bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many were bought, when the line says.","type":["number","null"]},"notes":{"description":"Free-text notes on this line.","type":["string","null"]},"foreign":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code it was paid in, such as EUR."},"amountMinor":{"type":"integer","description":"Amount in that currency in its minor unit, such as cents; negative is money out."},"amountDisplay":{"type":"string","description":"Amount in that currency ready to show, such as -£12.50."},"rate":{"description":"The exchange rate used to convert it to the account currency, if known.","type":["string","null"]},"asOf":{"description":"The day the rate was taken from (YYYY-MM-DD), if known.","type":["string","null"]}},"required":["currency","amountMinor","amountDisplay","rate","asOf"],"additionalProperties":false},{"type":"null"}],"description":"The amount in the currency it was paid in, when that differs from the account's."}},"required":["id","account","amountMinor","amountDisplay","kind","category","payee","itemName","quantity","notes","foreign"],"additionalProperties":false},"description":"The lines that make up the transaction; each moves money in one account."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"The tags on it."},"source":{"description":"Where it came from, such as manual or an import.","type":["string","null"]},"documents":{"description":"Documents attached to it. Only present when the key can read documents.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The document id."},"title":{"type":"string","description":"The document title."}},"required":["id","title"],"additionalProperties":false}},"createdAt":{"type":"string","description":"When it was added, ISO 8601 in UTC."},"updatedAt":{"type":"string","description":"When it last changed, ISO 8601 in UTC."},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting, to avoid overwriting a newer change."}},"required":["id","date","at","description","descriptionAuto","notes","kind","isTransfer","isRoundUp","amountMinor","amountDisplay","lines","tags","source","createdAt","updatedAt","version"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"txn_1","date":"2026-10-24","at":"2026-10-24T12:31:00.000Z","description":"Weekly shop","descriptionAuto":false,"notes":null,"kind":"expense","isTransfer":false,"isRoundUp":false,"amountMinor":-4210,"amountDisplay":"-£42.10","lines":[{"id":"line_1","account":{"id":"src_1","name":"Everyday card"},"amountMinor":-4210,"amountDisplay":"-£42.10","kind":"item","category":{"id":"cat_1","name":"Groceries"},"payee":{"id":"pay_1","name":"Corner Market"},"itemName":null,"quantity":null,"notes":null,"foreign":null}],"tags":[{"id":"tag_1","name":"Household"}],"source":"manual","createdAt":"2026-10-24T12:35:00.000Z","updatedAt":"2026-10-24T12:35:00.000Z","version":"1792845300000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"description":"`validation_failed`: `from` is after `to`, `minAmountMinor` is above `maxAmountMinor`, or the `cursor` is not one a previous page gave. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden_scope`: `hasDocuments` is used without the `documents:read` scope. The key lacks the `transactions:read` scope; `requiredScope` names it.\n\n`forbidden`: `hasDocuments` or `include=documents` is used by a key limited to some accounts (`reason: account_limit`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postTransactions","tags":["transactions"],"summary":"Create a transaction","description":"Posts a transaction to the ledger, as if you had entered it in the app. Send `lines` (each with non-negative `amountMinor`, including zero; the `kind` decides whether money goes out or in), or for one line the shorthand `accountId` + `amountMinor` + `categoryId` + `payeeId`. A transfer takes `fromAccountId`, `toAccountId` and `amountMinor` and is filed under the Transfer category and payee. `date` is a `YYYY-MM-DD` day (stored at midday UK time) or an ISO 8601 timestamp. Every expense or income line needs a category and a payee. Send an `Idempotency-Key` header to make a retry safe: the ledger itself ignores a second post with the same key. Answers 201 with the transaction, including its `version` for later edits.\n\nNeeds the `transactions:write` scope.","x-required-scope":"transactions:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"description":"The transaction’s date: `YYYY-MM-DD` (stored at midday UK time on that day) or an ISO 8601 timestamp for an exact moment.","type":"string"},"description":{"description":"What the transaction was, such as `Weekly shop`. Leave it out and the app writes one from the lines, such as `Bought 3 items at Corner Market for £43.50`, and keeps it up to date.","type":"string","minLength":1,"maxLength":2000},"descriptionStyle":{"description":"For a description the app writes: `long` (`Bought 3 items at Corner Market for £43.50`), `short` (`3 items · Corner Market · £43.50`) or `smart` (long when it fits in 60 characters). Defaults to your Settings choice.","type":"string","enum":["smart","long","short"]},"descriptionShowAmount":{"description":"For a description the app writes: whether it includes the amount. Defaults to your Settings choice.","type":"boolean"},"notes":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"description":"Private notes on the transaction; `null` clears them."},"kind":{"type":"string","enum":["expense","income","transfer"],"description":"`expense` takes money out, `income` puts money in, `transfer` moves it between two of your accounts."},"tagIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"description":"Tag ids. The transaction ends up with exactly these tags."},"lines":{"description":"The lines of an expense or income. Use these, or the single-line shorthand (`accountId`, `amountMinor`, `categoryId`, `payeeId`), not both.","minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string","minLength":1,"maxLength":100,"description":"A payment source id (card, pot or account activity), or a financial account id to use its Direct source."},"amountMinor":{"type":"integer","minimum":0,"maximum":2147483647,"description":"The line’s size in pence, a whole number that may be zero. The sign comes from the transaction’s `kind` (an expense takes money out, income puts it in); an `adjustment` line such as a discount goes the other way."},"categoryId":{"description":"The category to file this line under.","type":"string","minLength":1,"maxLength":100},"payeeId":{"description":"The payee for this line.","type":"string","minLength":1,"maxLength":100},"itemName":{"description":"What was bought, for itemised receipts.","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"quantity":{"description":"How many were bought (1 if left out).","anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":99999999},{"type":"null"}]},"notes":{"description":"A private note on this line.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"kind":{"description":"`item` (the default), `adjustment` (a discount or voucher that reduces the total) or `surcharge` (a tip, tax or fee that adds to it).","type":"string","enum":["item","adjustment","surcharge"]}},"required":["accountId","amountMinor"],"additionalProperties":false}},"accountId":{"description":"Single-line shorthand instead of `lines`. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100},"amountMinor":{"description":"Single-line shorthand: the amount in pence (zero allowed). For a transfer, the amount moved.","type":"integer","minimum":0,"maximum":2147483647},"categoryId":{"description":"Single-line shorthand: the category.","type":"string","minLength":1,"maxLength":100},"payeeId":{"description":"Single-line shorthand: the payee.","type":"string","minLength":1,"maxLength":100},"fromAccountId":{"description":"Transfers only: where the money leaves. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100},"toAccountId":{"description":"Transfers only: where the money arrives. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100}},"required":["date","kind"],"additionalProperties":false},"example":{"date":"2026-10-24","description":"Weekly shop","kind":"expense","tagIds":["tag_1"],"accountId":"src_1","amountMinor":4210,"categoryId":"cat_1","payeeId":"pay_1"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The transaction id."},"date":{"type":"string","description":"The day it happened, YYYY-MM-DD in UK time."},"at":{"type":"string","description":"The moment it happened, ISO 8601 in UTC."},"description":{"type":"string","description":"What the transaction is called."},"descriptionAuto":{"type":"boolean","description":"True when the app writes the description from the lines, and rewrites it when they change."},"notes":{"description":"Free-text notes.","type":["string","null"]},"kind":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money went out, came in, or moved between your own accounts."},"isTransfer":{"type":"boolean","description":"True for a move between your own accounts."},"isRoundUp":{"type":"boolean","description":"True for a round-up transfer into savings."},"amountMinor":{"type":"integer","description":"Net amount of all lines in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Net amount of all lines ready to show, such as -£12.50."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line id."},"account":{"type":"object","properties":{"id":{"description":"Its id; null for another account, to a key limited to some accounts.","type":["string","null"]},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account this line moves money in or out of. For a key limited to some accounts, a line on another account shows `{ \"id\": null, \"name\": \"Another account\" }`.","additionalProperties":false},"amountMinor":{"type":"integer","description":"Amount of this line in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Amount of this line ready to show, such as -£12.50."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line's category, or null when it has none."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who was paid, or null when none is set."},"itemName":{"description":"What was bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many were bought, when the line says.","type":["number","null"]},"notes":{"description":"Free-text notes on this line.","type":["string","null"]},"foreign":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code it was paid in, such as EUR."},"amountMinor":{"type":"integer","description":"Amount in that currency in its minor unit, such as cents; negative is money out."},"amountDisplay":{"type":"string","description":"Amount in that currency ready to show, such as -£12.50."},"rate":{"description":"The exchange rate used to convert it to the account currency, if known.","type":["string","null"]},"asOf":{"description":"The day the rate was taken from (YYYY-MM-DD), if known.","type":["string","null"]}},"required":["currency","amountMinor","amountDisplay","rate","asOf"],"additionalProperties":false},{"type":"null"}],"description":"The amount in the currency it was paid in, when that differs from the account's."}},"required":["id","account","amountMinor","amountDisplay","kind","category","payee","itemName","quantity","notes","foreign"],"additionalProperties":false},"description":"The lines that make up the transaction; each moves money in one account."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"The tags on it."},"source":{"description":"Where it came from, such as manual or an import.","type":["string","null"]},"documents":{"description":"Documents attached to it. Only present when the key can read documents.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The document id."},"title":{"type":"string","description":"The document title."}},"required":["id","title"],"additionalProperties":false}},"createdAt":{"type":"string","description":"When it was added, ISO 8601 in UTC."},"updatedAt":{"type":"string","description":"When it last changed, ISO 8601 in UTC."},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting, to avoid overwriting a newer change."}},"required":["id","date","at","description","descriptionAuto","notes","kind","isTransfer","isRoundUp","amountMinor","amountDisplay","lines","tags","source","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"txn_1","date":"2026-10-24","at":"2026-10-24T12:31:00.000Z","description":"Weekly shop","descriptionAuto":false,"notes":null,"kind":"expense","isTransfer":false,"isRoundUp":false,"amountMinor":-4210,"amountDisplay":"-£42.10","lines":[{"id":"line_1","account":{"id":"src_1","name":"Everyday card"},"amountMinor":-4210,"amountDisplay":"-£42.10","kind":"item","category":{"id":"cat_1","name":"Groceries"},"payee":{"id":"pay_1","name":"Corner Market"},"itemName":null,"quantity":null,"notes":null,"foreign":null}],"tags":[{"id":"tag_1","name":"Household"}],"source":"manual","createdAt":"2026-10-24T12:35:00.000Z","updatedAt":"2026-10-24T12:35:00.000Z","version":"1792845300000"}}}}},"400":{"description":"`validation_failed`: The lines do not add up, an expense or income line has no category or payee, or a transfer goes to the same account. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `transactions:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: An account, category, payee or tag in the body does not exist or belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"description":"`idempotency_conflict`: The ledger already holds a post under this `Idempotency-Key` for a different transaction. The `Idempotency-Key` was already used with a different request.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/transactions/lines":{"get":{"operationId":"getTransactionsLines","tags":["transactions"],"summary":"List transaction lines","description":"One row per ledger line, newest transaction first and each transaction’s lines in the order they were entered, for scripts that want a flat table. Each row names its transaction. Here `minAmountMinor` / `maxAmountMinor` compare the line’s own absolute amount, and account, category, payee and text filters match the line itself (a parent category or payee also matches its subcategories and sub-payees).\n\nNeeds the `transactions:read` scope.","x-required-scope":"transactions:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Earliest date, inclusive. `YYYY-MM-DD` (a whole UK day) or an ISO 8601 timestamp.","schema":{"type":"string"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"Latest date, inclusive. `YYYY-MM-DD` runs to the end of that UK day; a timestamp is that instant.","schema":{"type":"string"}},{"name":"accountId","in":"query","required":false,"description":"A payment source (card, pot or account activity) id, or a financial account id for all of its sources.","schema":{"type":"string","minLength":1}},{"name":"categoryId","in":"query","required":false,"description":"Only transactions with a line in this category or any category under it (a parent category includes its subcategories, as on the Transactions page).","schema":{"type":"string","minLength":1}},{"name":"payeeId","in":"query","required":false,"description":"Only transactions with a line for this payee or any payee under it (a parent payee includes its sub-payees).","schema":{"type":"string","minLength":1}},{"name":"tagId","in":"query","required":false,"description":"Only transactions carrying this tag.","schema":{"type":"string","minLength":1}},{"name":"kind","in":"query","required":false,"description":"Expense, income or transfer, read from all of a transaction’s lines as the app does.","schema":{"type":"string","enum":["expense","income","transfer"]}},{"name":"minAmountMinor","in":"query","required":false,"description":"Smallest absolute amount in pence, up to 2147483647.","schema":{"type":"integer","minimum":0,"maximum":2147483647}},{"name":"maxAmountMinor","in":"query","required":false,"description":"Largest absolute amount in pence, up to 2147483647.","schema":{"type":"integer","minimum":0,"maximum":2147483647}},{"name":"q","in":"query","required":false,"description":"Text search over the description, notes and item names, with the same AND / OR / NOT, \"quotes\" and accent folding as the Transactions page.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"hasDocuments","in":"query","required":false,"description":"`true` for transactions with documents attached, `false` for those without. Needs the `documents:read` scope and a key for all accounts.","schema":{"type":"string","enum":["0","1","true","false"]}},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check). A line counts as changed when it or its transaction’s header was. Deleted lines never appear.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Lines per page, 1–200 (50 by default).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"example":"20"},{"name":"cursor","in":"query","required":false,"description":"`page.nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line id."},"account":{"type":"object","properties":{"id":{"description":"Its id; null for another account, to a key limited to some accounts.","type":["string","null"]},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account this line moves money in or out of. For a key limited to some accounts, a line on another account shows `{ \"id\": null, \"name\": \"Another account\" }`.","additionalProperties":false},"amountMinor":{"type":"integer","description":"Amount of this line in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Amount of this line ready to show, such as -£12.50."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line's category, or null when it has none."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who was paid, or null when none is set."},"itemName":{"description":"What was bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many were bought, when the line says.","type":["number","null"]},"notes":{"description":"Free-text notes on this line.","type":["string","null"]},"foreign":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code it was paid in, such as EUR."},"amountMinor":{"type":"integer","description":"Amount in that currency in its minor unit, such as cents; negative is money out."},"amountDisplay":{"type":"string","description":"Amount in that currency ready to show, such as -£12.50."},"rate":{"description":"The exchange rate used to convert it to the account currency, if known.","type":["string","null"]},"asOf":{"description":"The day the rate was taken from (YYYY-MM-DD), if known.","type":["string","null"]}},"required":["currency","amountMinor","amountDisplay","rate","asOf"],"additionalProperties":false},{"type":"null"}],"description":"The amount in the currency it was paid in, when that differs from the account's."},"transaction":{"type":"object","properties":{"id":{"type":"string","description":"The transaction id."},"date":{"type":"string","description":"The day it happened, YYYY-MM-DD in UK time."},"at":{"type":"string","description":"The moment it happened, ISO 8601 in UTC."},"description":{"type":"string","description":"What the transaction is called."},"kind":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money went out, came in, or moved between your own accounts."},"isTransfer":{"type":"boolean","description":"True for a move between your own accounts."},"isRoundUp":{"type":"boolean","description":"True for a round-up transfer into savings."}},"required":["id","date","at","description","kind","isTransfer","isRoundUp"],"description":"The transaction this line belongs to.","additionalProperties":false}},"required":["id","account","amountMinor","amountDisplay","kind","category","payee","itemName","quantity","notes","foreign","transaction"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"line_1","account":{"id":"src_1","name":"Everyday card"},"amountMinor":-4210,"amountDisplay":"-£42.10","kind":"item","category":{"id":"cat_1","name":"Groceries"},"payee":{"id":"pay_1","name":"Corner Market"},"itemName":null,"quantity":null,"notes":null,"foreign":null,"transaction":{"id":"txn_1","date":"2026-10-24","at":"2026-10-24T12:31:00.000Z","description":"Weekly shop","kind":"expense","isTransfer":false,"isRoundUp":false}}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"description":"`validation_failed`: `from` is after `to`, `minAmountMinor` is above `maxAmountMinor`, or the `cursor` is not one a previous page gave. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden_scope`: `hasDocuments` is used without the `documents:read` scope. The key lacks the `transactions:read` scope; `requiredScope` names it.\n\n`forbidden`: `hasDocuments` or `include=documents` is used by a key limited to some accounts (`reason: account_limit`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/transactions/{id}":{"get":{"operationId":"getTransactionsById","tags":["transactions"],"summary":"Get a transaction","description":"One transaction with its lines and tags. A key that also has `documents:read` gets the attached documents (id and title); without it, or for a key limited to some accounts, the field is left out. A ledger line id from `/api/transactions` also finds its transaction.\n\nNeeds the `transactions:read` scope.","x-required-scope":"transactions:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The transaction id.","schema":{"type":"string","minLength":1},"example":"txn_1"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The transaction id."},"date":{"type":"string","description":"The day it happened, YYYY-MM-DD in UK time."},"at":{"type":"string","description":"The moment it happened, ISO 8601 in UTC."},"description":{"type":"string","description":"What the transaction is called."},"descriptionAuto":{"type":"boolean","description":"True when the app writes the description from the lines, and rewrites it when they change."},"notes":{"description":"Free-text notes.","type":["string","null"]},"kind":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money went out, came in, or moved between your own accounts."},"isTransfer":{"type":"boolean","description":"True for a move between your own accounts."},"isRoundUp":{"type":"boolean","description":"True for a round-up transfer into savings."},"amountMinor":{"type":"integer","description":"Net amount of all lines in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Net amount of all lines ready to show, such as -£12.50."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line id."},"account":{"type":"object","properties":{"id":{"description":"Its id; null for another account, to a key limited to some accounts.","type":["string","null"]},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account this line moves money in or out of. For a key limited to some accounts, a line on another account shows `{ \"id\": null, \"name\": \"Another account\" }`.","additionalProperties":false},"amountMinor":{"type":"integer","description":"Amount of this line in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Amount of this line ready to show, such as -£12.50."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line's category, or null when it has none."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who was paid, or null when none is set."},"itemName":{"description":"What was bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many were bought, when the line says.","type":["number","null"]},"notes":{"description":"Free-text notes on this line.","type":["string","null"]},"foreign":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code it was paid in, such as EUR."},"amountMinor":{"type":"integer","description":"Amount in that currency in its minor unit, such as cents; negative is money out."},"amountDisplay":{"type":"string","description":"Amount in that currency ready to show, such as -£12.50."},"rate":{"description":"The exchange rate used to convert it to the account currency, if known.","type":["string","null"]},"asOf":{"description":"The day the rate was taken from (YYYY-MM-DD), if known.","type":["string","null"]}},"required":["currency","amountMinor","amountDisplay","rate","asOf"],"additionalProperties":false},{"type":"null"}],"description":"The amount in the currency it was paid in, when that differs from the account's."}},"required":["id","account","amountMinor","amountDisplay","kind","category","payee","itemName","quantity","notes","foreign"],"additionalProperties":false},"description":"The lines that make up the transaction; each moves money in one account."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"The tags on it."},"source":{"description":"Where it came from, such as manual or an import.","type":["string","null"]},"documents":{"description":"Documents attached to it. Only present when the key can read documents.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The document id."},"title":{"type":"string","description":"The document title."}},"required":["id","title"],"additionalProperties":false}},"createdAt":{"type":"string","description":"When it was added, ISO 8601 in UTC."},"updatedAt":{"type":"string","description":"When it last changed, ISO 8601 in UTC."},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting, to avoid overwriting a newer change."}},"required":["id","date","at","description","descriptionAuto","notes","kind","isTransfer","isRoundUp","amountMinor","amountDisplay","lines","tags","source","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"txn_1","date":"2026-10-24","at":"2026-10-24T12:31:00.000Z","description":"Weekly shop","descriptionAuto":false,"notes":null,"kind":"expense","isTransfer":false,"isRoundUp":false,"amountMinor":-4210,"amountDisplay":"-£42.10","lines":[{"id":"line_1","account":{"id":"src_1","name":"Everyday card"},"amountMinor":-4210,"amountDisplay":"-£42.10","kind":"item","category":{"id":"cat_1","name":"Groceries"},"payee":{"id":"pay_1","name":"Corner Market"},"itemName":null,"quantity":null,"notes":null,"foreign":null}],"tags":[{"id":"tag_1","name":"Household"}],"source":"manual","createdAt":"2026-10-24T12:35:00.000Z","updatedAt":"2026-10-24T12:35:00.000Z","version":"1792845300000"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"patchTransactionsById","tags":["transactions"],"summary":"Edit a transaction","description":"Changes the fields you send and leaves the rest. `lines` replaces the whole line list: a line with its `id` keeps that saved line (fields you leave out keep their saved value), a line without an `id` is added, and a saved line you leave out is removed. For a single-line transaction you can send just `amountMinor`, `categoryId`, `payeeId` or `accountId`; for a transfer, `fromAccountId`, `toAccountId` and `amountMinor`. Amounts are non-negative (zero allowed): the `kind` decides the sign. `tagIds` sets exactly those tags. Send the `version` from your last read as `If-Match` (or in the body) so an edit made elsewhere is not overwritten: a stale version answers 412. Answers with the edited transaction.\n\nNeeds the `transactions:write` scope.","x-required-scope":"transactions:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The transaction id.","schema":{"type":"string","minLength":1},"example":"txn_1"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"description":"The transaction’s date: `YYYY-MM-DD` (stored at midday UK time on that day) or an ISO 8601 timestamp for an exact moment.","type":"string"},"description":{"description":"A new description; `null` hands it back to the app, which writes it from the lines.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"descriptionStyle":{"description":"For a description the app writes: `long` (`Bought 3 items at Corner Market for £43.50`), `short` (`3 items · Corner Market · £43.50`) or `smart` (long when it fits in 60 characters). Defaults to your Settings choice.","type":"string","enum":["smart","long","short"]},"descriptionShowAmount":{"description":"For a description the app writes: whether it includes the amount. Defaults to your Settings choice.","type":"boolean"},"notes":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"description":"Private notes on the transaction; `null` clears them."},"kind":{"description":"Change the kind. Send `lines` (or the transfer fields) with it, since the amounts change sign.","type":"string","enum":["expense","income","transfer"]},"tagIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"description":"Tag ids. The transaction ends up with exactly these tags."},"lines":{"description":"The full list of lines. A line with an `id` keeps that saved line; one without is added; a saved line left out is removed.","minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"id":{"description":"The id of an existing line to keep. Fields you leave out keep their saved value. Leave `id` out to add a new line, which needs every required field.","type":"string","minLength":1,"maxLength":100},"accountId":{"description":"A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100},"amountMinor":{"type":"integer","minimum":0,"maximum":2147483647,"description":"The line’s size in pence, a whole number that may be zero. The sign comes from the transaction’s `kind` (an expense takes money out, income puts it in); an `adjustment` line such as a discount goes the other way."},"categoryId":{"description":"The category to file this line under.","type":"string","minLength":1,"maxLength":100},"payeeId":{"description":"The payee for this line.","type":"string","minLength":1,"maxLength":100},"itemName":{"description":"What was bought, for itemised receipts.","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"quantity":{"description":"How many were bought (1 if left out).","anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":99999999},{"type":"null"}]},"notes":{"description":"A private note on this line.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"kind":{"description":"`item` (the default), `adjustment` (a discount or voucher that reduces the total) or `surcharge` (a tip, tax or fee that adds to it).","type":"string","enum":["item","adjustment","surcharge"]}},"additionalProperties":false}},"accountId":{"description":"Single-line shorthand instead of `lines`. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100},"amountMinor":{"description":"Single-line shorthand: the amount in pence (zero allowed). For a transfer, the amount moved.","type":"integer","minimum":0,"maximum":2147483647},"categoryId":{"description":"Single-line shorthand: the category.","type":"string","minLength":1,"maxLength":100},"payeeId":{"description":"Single-line shorthand: the payee.","type":"string","minLength":1,"maxLength":100},"fromAccountId":{"description":"Transfers only: where the money leaves. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100},"toAccountId":{"description":"Transfers only: where the money arrives. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100},"version":{"description":"The `version` from your last read, as an alternative to the `If-Match` header.","type":["string","number"]}},"additionalProperties":false},"example":{"description":"Weekly shop (Corner Market)","lines":[{"id":"line_1","amountMinor":4350}]}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The transaction id."},"date":{"type":"string","description":"The day it happened, YYYY-MM-DD in UK time."},"at":{"type":"string","description":"The moment it happened, ISO 8601 in UTC."},"description":{"type":"string","description":"What the transaction is called."},"descriptionAuto":{"type":"boolean","description":"True when the app writes the description from the lines, and rewrites it when they change."},"notes":{"description":"Free-text notes.","type":["string","null"]},"kind":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money went out, came in, or moved between your own accounts."},"isTransfer":{"type":"boolean","description":"True for a move between your own accounts."},"isRoundUp":{"type":"boolean","description":"True for a round-up transfer into savings."},"amountMinor":{"type":"integer","description":"Net amount of all lines in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Net amount of all lines ready to show, such as -£12.50."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line id."},"account":{"type":"object","properties":{"id":{"description":"Its id; null for another account, to a key limited to some accounts.","type":["string","null"]},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account this line moves money in or out of. For a key limited to some accounts, a line on another account shows `{ \"id\": null, \"name\": \"Another account\" }`.","additionalProperties":false},"amountMinor":{"type":"integer","description":"Amount of this line in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Amount of this line ready to show, such as -£12.50."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line's category, or null when it has none."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who was paid, or null when none is set."},"itemName":{"description":"What was bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many were bought, when the line says.","type":["number","null"]},"notes":{"description":"Free-text notes on this line.","type":["string","null"]},"foreign":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code it was paid in, such as EUR."},"amountMinor":{"type":"integer","description":"Amount in that currency in its minor unit, such as cents; negative is money out."},"amountDisplay":{"type":"string","description":"Amount in that currency ready to show, such as -£12.50."},"rate":{"description":"The exchange rate used to convert it to the account currency, if known.","type":["string","null"]},"asOf":{"description":"The day the rate was taken from (YYYY-MM-DD), if known.","type":["string","null"]}},"required":["currency","amountMinor","amountDisplay","rate","asOf"],"additionalProperties":false},{"type":"null"}],"description":"The amount in the currency it was paid in, when that differs from the account's."}},"required":["id","account","amountMinor","amountDisplay","kind","category","payee","itemName","quantity","notes","foreign"],"additionalProperties":false},"description":"The lines that make up the transaction; each moves money in one account."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"The tags on it."},"source":{"description":"Where it came from, such as manual or an import.","type":["string","null"]},"documents":{"description":"Documents attached to it. Only present when the key can read documents.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The document id."},"title":{"type":"string","description":"The document title."}},"required":["id","title"],"additionalProperties":false}},"createdAt":{"type":"string","description":"When it was added, ISO 8601 in UTC."},"updatedAt":{"type":"string","description":"When it last changed, ISO 8601 in UTC."},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting, to avoid overwriting a newer change."}},"required":["id","date","at","description","descriptionAuto","notes","kind","isTransfer","isRoundUp","amountMinor","amountDisplay","lines","tags","source","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"txn_1","date":"2026-10-24","at":"2026-10-24T12:31:00.000Z","description":"Weekly shop","descriptionAuto":false,"notes":null,"kind":"expense","isTransfer":false,"isRoundUp":false,"amountMinor":-4210,"amountDisplay":"-£42.10","lines":[{"id":"line_1","account":{"id":"src_1","name":"Everyday card"},"amountMinor":-4210,"amountDisplay":"-£42.10","kind":"item","category":{"id":"cat_1","name":"Groceries"},"payee":{"id":"pay_1","name":"Corner Market"},"itemName":null,"quantity":null,"notes":null,"foreign":null}],"tags":[{"id":"tag_1","name":"Household"}],"source":"manual","createdAt":"2026-10-24T12:35:00.000Z","updatedAt":"2026-10-24T12:35:00.000Z","version":"1792845300000"}}}}},"400":{"description":"`validation_failed`: The body is empty, a line `id` is not one of this transaction's lines, or `kind` changes without `lines`. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `transactions:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: A category, payee, account or tag in the body does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"deleteTransactionsById","tags":["transactions"],"summary":"Delete a transaction","description":"Deletes the transaction and its lines. The API has no undo: for 30 days it can be restored in the app, from Settings › Clean Up. Recurring and scheduled items that pointed at it are detached (the occurrence is skipped, the scheduled item cancelled). A transaction that has refunds or chargebacks linked to it, or that is an account’s opening balance, can’t be deleted: 409 `conflict` says why. Attached documents are kept (unfiled) unless you send `documents=delete`, which moves the ones only attached here to the trash and also needs the `documents:delete` scope (a key limited to some accounts can’t send it). Send `If-Match` to refuse the delete if the transaction changed. Answers 204.\n\nNeeds the `transactions:delete` scope.","x-required-scope":"transactions:delete","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The transaction id.","schema":{"type":"string","minLength":1},"example":"txn_1"},{"name":"documents","in":"query","required":false,"description":"`keep` (the default) leaves attached documents unfiled; `delete` moves documents attached only to this transaction to the trash.","schema":{"default":"keep","type":"string","enum":["keep","delete"]},"example":"keep"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"responses":{"204":{"description":"Done. There is no body.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden_scope`: `documents=delete` is sent without the `documents:delete` scope. The key lacks the `transactions:delete` scope; `requiredScope` names it.\n\n`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`). `documents=delete` is sent by a key limited to some accounts (`reason: account_limit`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`conflict`: The transaction has linked refunds or chargebacks (`reason: has_linked_refunds`), or is an account's opening balance (`reason: opening_balance`).\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/transactions/{id}/tags":{"put":{"operationId":"putTransactionsByIdTags","tags":["transactions"],"summary":"Set a transaction’s tags","description":"Replaces the transaction’s tags with exactly the ones in `tagIds` (an empty list removes them all). A change of tags is a change to the transaction: its `updatedAt` and `version` move on, so `updatedSince` finds it. Answers with the transaction.\n\nNeeds the `transactions:write` scope.","x-required-scope":"transactions:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The transaction id.","schema":{"type":"string","minLength":1},"example":"txn_1"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tagIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"description":"Tag ids. The transaction ends up with exactly these tags."},"version":{"description":"The `version` from your last read, as an alternative to the `If-Match` header.","type":["string","number"]}},"required":["tagIds"],"additionalProperties":false},"example":{"tagIds":["tag_1","tag_2"]}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The transaction id."},"date":{"type":"string","description":"The day it happened, YYYY-MM-DD in UK time."},"at":{"type":"string","description":"The moment it happened, ISO 8601 in UTC."},"description":{"type":"string","description":"What the transaction is called."},"descriptionAuto":{"type":"boolean","description":"True when the app writes the description from the lines, and rewrites it when they change."},"notes":{"description":"Free-text notes.","type":["string","null"]},"kind":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money went out, came in, or moved between your own accounts."},"isTransfer":{"type":"boolean","description":"True for a move between your own accounts."},"isRoundUp":{"type":"boolean","description":"True for a round-up transfer into savings."},"amountMinor":{"type":"integer","description":"Net amount of all lines in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Net amount of all lines ready to show, such as -£12.50."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line id."},"account":{"type":"object","properties":{"id":{"description":"Its id; null for another account, to a key limited to some accounts.","type":["string","null"]},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account this line moves money in or out of. For a key limited to some accounts, a line on another account shows `{ \"id\": null, \"name\": \"Another account\" }`.","additionalProperties":false},"amountMinor":{"type":"integer","description":"Amount of this line in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Amount of this line ready to show, such as -£12.50."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line's category, or null when it has none."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who was paid, or null when none is set."},"itemName":{"description":"What was bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many were bought, when the line says.","type":["number","null"]},"notes":{"description":"Free-text notes on this line.","type":["string","null"]},"foreign":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code it was paid in, such as EUR."},"amountMinor":{"type":"integer","description":"Amount in that currency in its minor unit, such as cents; negative is money out."},"amountDisplay":{"type":"string","description":"Amount in that currency ready to show, such as -£12.50."},"rate":{"description":"The exchange rate used to convert it to the account currency, if known.","type":["string","null"]},"asOf":{"description":"The day the rate was taken from (YYYY-MM-DD), if known.","type":["string","null"]}},"required":["currency","amountMinor","amountDisplay","rate","asOf"],"additionalProperties":false},{"type":"null"}],"description":"The amount in the currency it was paid in, when that differs from the account's."}},"required":["id","account","amountMinor","amountDisplay","kind","category","payee","itemName","quantity","notes","foreign"],"additionalProperties":false},"description":"The lines that make up the transaction; each moves money in one account."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"The tags on it."},"source":{"description":"Where it came from, such as manual or an import.","type":["string","null"]},"documents":{"description":"Documents attached to it. Only present when the key can read documents.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The document id."},"title":{"type":"string","description":"The document title."}},"required":["id","title"],"additionalProperties":false}},"createdAt":{"type":"string","description":"When it was added, ISO 8601 in UTC."},"updatedAt":{"type":"string","description":"When it last changed, ISO 8601 in UTC."},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting, to avoid overwriting a newer change."}},"required":["id","date","at","description","descriptionAuto","notes","kind","isTransfer","isRoundUp","amountMinor","amountDisplay","lines","tags","source","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"txn_1","date":"2026-10-24","at":"2026-10-24T12:31:00.000Z","description":"Weekly shop","descriptionAuto":false,"notes":null,"kind":"expense","isTransfer":false,"isRoundUp":false,"amountMinor":-4210,"amountDisplay":"-£42.10","lines":[{"id":"line_1","account":{"id":"src_1","name":"Everyday card"},"amountMinor":-4210,"amountDisplay":"-£42.10","kind":"item","category":{"id":"cat_1","name":"Groceries"},"payee":{"id":"pay_1","name":"Corner Market"},"itemName":null,"quantity":null,"notes":null,"foreign":null}],"tags":[{"id":"tag_1","name":"Household"}],"source":"manual","createdAt":"2026-10-24T12:35:00.000Z","updatedAt":"2026-10-24T12:35:00.000Z","version":"1792845300000"}}}}},"400":{"description":"`validation_failed`: A tag id in `tagIds` is not one of your tags. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `transactions:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/transactions/batch":{"post":{"operationId":"postTransactionsBatch","tags":["transactions"],"summary":"Create many transactions at once","description":"Posts 1–100 transactions in one call. Each item in `transactions` is exactly the body of `POST /transactions`. The batch is all or nothing: if any item is invalid, or the ledger refuses it, nothing is created and the 400 names the item in `details` (for example `body.transactions.3.amountMinor`). Answers 201 with the created transactions in the order you sent them. Send an `Idempotency-Key` header to make a retry safe: the same key with the same batch answers the first result again, and the ledger itself ignores a second post of any item under its key. The call counts once against the rate limit. For a key limited to some accounts, an item that names another account refuses the whole batch with a 403 naming the item.\n\nNeeds the `transactions:write` scope.","x-required-scope":"transactions:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"transactions":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"date":{"description":"The transaction’s date: `YYYY-MM-DD` (stored at midday UK time on that day) or an ISO 8601 timestamp for an exact moment.","type":"string"},"description":{"description":"What the transaction was, such as `Weekly shop`. Leave it out and the app writes one from the lines, such as `Bought 3 items at Corner Market for £43.50`, and keeps it up to date.","type":"string","minLength":1,"maxLength":2000},"descriptionStyle":{"description":"For a description the app writes: `long` (`Bought 3 items at Corner Market for £43.50`), `short` (`3 items · Corner Market · £43.50`) or `smart` (long when it fits in 60 characters). Defaults to your Settings choice.","type":"string","enum":["smart","long","short"]},"descriptionShowAmount":{"description":"For a description the app writes: whether it includes the amount. Defaults to your Settings choice.","type":"boolean"},"notes":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"description":"Private notes on the transaction; `null` clears them."},"kind":{"type":"string","enum":["expense","income","transfer"],"description":"`expense` takes money out, `income` puts money in, `transfer` moves it between two of your accounts."},"tagIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"description":"Tag ids. The transaction ends up with exactly these tags."},"lines":{"description":"The lines of an expense or income. Use these, or the single-line shorthand (`accountId`, `amountMinor`, `categoryId`, `payeeId`), not both.","minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string","minLength":1,"maxLength":100,"description":"A payment source id (card, pot or account activity), or a financial account id to use its Direct source."},"amountMinor":{"type":"integer","minimum":0,"maximum":2147483647,"description":"The line’s size in pence, a whole number that may be zero. The sign comes from the transaction’s `kind` (an expense takes money out, income puts it in); an `adjustment` line such as a discount goes the other way."},"categoryId":{"description":"The category to file this line under.","type":"string","minLength":1,"maxLength":100},"payeeId":{"description":"The payee for this line.","type":"string","minLength":1,"maxLength":100},"itemName":{"description":"What was bought, for itemised receipts.","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"quantity":{"description":"How many were bought (1 if left out).","anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":99999999},{"type":"null"}]},"notes":{"description":"A private note on this line.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"kind":{"description":"`item` (the default), `adjustment` (a discount or voucher that reduces the total) or `surcharge` (a tip, tax or fee that adds to it).","type":"string","enum":["item","adjustment","surcharge"]}},"required":["accountId","amountMinor"],"additionalProperties":false}},"accountId":{"description":"Single-line shorthand instead of `lines`. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100},"amountMinor":{"description":"Single-line shorthand: the amount in pence (zero allowed). For a transfer, the amount moved.","type":"integer","minimum":0,"maximum":2147483647},"categoryId":{"description":"Single-line shorthand: the category.","type":"string","minLength":1,"maxLength":100},"payeeId":{"description":"Single-line shorthand: the payee.","type":"string","minLength":1,"maxLength":100},"fromAccountId":{"description":"Transfers only: where the money leaves. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100},"toAccountId":{"description":"Transfers only: where the money arrives. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.","type":"string","minLength":1,"maxLength":100}},"required":["date","kind"],"additionalProperties":false},"description":"1–100 transactions, each exactly the body of POST /transactions."}},"required":["transactions"],"additionalProperties":false},"example":{"transactions":[{"date":"2026-10-24","description":"Weekly shop","kind":"expense","tagIds":["tag_1"],"accountId":"src_1","amountMinor":4210,"categoryId":"cat_1","payeeId":"pay_1"},{"date":"2026-10-23","description":"Lunch","kind":"expense","accountId":"src_1","amountMinor":840,"categoryId":"cat_2","payeeId":"pay_2"}]}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The transaction id."},"date":{"type":"string","description":"The day it happened, YYYY-MM-DD in UK time."},"at":{"type":"string","description":"The moment it happened, ISO 8601 in UTC."},"description":{"type":"string","description":"What the transaction is called."},"descriptionAuto":{"type":"boolean","description":"True when the app writes the description from the lines, and rewrites it when they change."},"notes":{"description":"Free-text notes.","type":["string","null"]},"kind":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money went out, came in, or moved between your own accounts."},"isTransfer":{"type":"boolean","description":"True for a move between your own accounts."},"isRoundUp":{"type":"boolean","description":"True for a round-up transfer into savings."},"amountMinor":{"type":"integer","description":"Net amount of all lines in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Net amount of all lines ready to show, such as -£12.50."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line id."},"account":{"type":"object","properties":{"id":{"description":"Its id; null for another account, to a key limited to some accounts.","type":["string","null"]},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account this line moves money in or out of. For a key limited to some accounts, a line on another account shows `{ \"id\": null, \"name\": \"Another account\" }`.","additionalProperties":false},"amountMinor":{"type":"integer","description":"Amount of this line in pence; negative is money out."},"amountDisplay":{"type":"string","description":"Amount of this line ready to show, such as -£12.50."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line's category, or null when it has none."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who was paid, or null when none is set."},"itemName":{"description":"What was bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many were bought, when the line says.","type":["number","null"]},"notes":{"description":"Free-text notes on this line.","type":["string","null"]},"foreign":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code it was paid in, such as EUR."},"amountMinor":{"type":"integer","description":"Amount in that currency in its minor unit, such as cents; negative is money out."},"amountDisplay":{"type":"string","description":"Amount in that currency ready to show, such as -£12.50."},"rate":{"description":"The exchange rate used to convert it to the account currency, if known.","type":["string","null"]},"asOf":{"description":"The day the rate was taken from (YYYY-MM-DD), if known.","type":["string","null"]}},"required":["currency","amountMinor","amountDisplay","rate","asOf"],"additionalProperties":false},{"type":"null"}],"description":"The amount in the currency it was paid in, when that differs from the account's."}},"required":["id","account","amountMinor","amountDisplay","kind","category","payee","itemName","quantity","notes","foreign"],"additionalProperties":false},"description":"The lines that make up the transaction; each moves money in one account."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"The tags on it."},"source":{"description":"Where it came from, such as manual or an import.","type":["string","null"]},"documents":{"description":"Documents attached to it. Only present when the key can read documents.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The document id."},"title":{"type":"string","description":"The document title."}},"required":["id","title"],"additionalProperties":false}},"createdAt":{"type":"string","description":"When it was added, ISO 8601 in UTC."},"updatedAt":{"type":"string","description":"When it last changed, ISO 8601 in UTC."},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting, to avoid overwriting a newer change."}},"required":["id","date","at","description","descriptionAuto","notes","kind","isTransfer","isRoundUp","amountMinor","amountDisplay","lines","tags","source","createdAt","updatedAt","version"],"additionalProperties":false}}}},"example":{"data":[{"id":"txn_1","date":"2026-10-24","at":"2026-10-24T12:31:00.000Z","description":"Weekly shop","descriptionAuto":false,"notes":null,"kind":"expense","isTransfer":false,"isRoundUp":false,"amountMinor":-4210,"amountDisplay":"-£42.10","lines":[{"id":"line_1","account":{"id":"src_1","name":"Everyday card"},"amountMinor":-4210,"amountDisplay":"-£42.10","kind":"item","category":{"id":"cat_1","name":"Groceries"},"payee":{"id":"pay_1","name":"Corner Market"},"itemName":null,"quantity":null,"notes":null,"foreign":null}],"tags":[{"id":"tag_1","name":"Household"}],"source":"manual","createdAt":"2026-10-24T12:35:00.000Z","updatedAt":"2026-10-24T12:35:00.000Z","version":"1792845300000"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and an item names another one; nothing is created and `details` names the item (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `transactions:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/transactions/export":{"get":{"operationId":"getTransactionsExport","tags":["transactions"],"summary":"Export transactions as CSV","description":"A CSV file of your transactions, one row per ledger line, newest first, with the same filters as `GET /transactions` (`from`, `to`, `accountId`, `categoryId`, `payeeId`, `tagId`, `kind`, `q`, amounts). Columns: `date`, `transactionId`, `description`, `kind`, `account`, `category`, `payee`, `tags` (names, `; `-separated), `amount` (pounds as a plain decimal, negative when money goes out), `amountMinor` (pence), `currency` and `notes` (the line’s note). Text that a spreadsheet would read as a formula starts with `'` so it opens as text. A file holds at most 10,000 lines: if more match, the answer is a 400 asking you to narrow the dates. Answers `text/csv` as an attachment named `transactions-YYYY-MM-DD.csv`, not the usual JSON envelope. A key limited to some accounts gets the transactions on its accounts, with a line on another account (the other side of a transfer) under `Another account`.\n\nNeeds the `transactions:read` scope.","x-required-scope":"transactions:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Earliest date, inclusive. `YYYY-MM-DD` (a whole UK day) or an ISO 8601 timestamp.","schema":{"type":"string"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"Latest date, inclusive. `YYYY-MM-DD` runs to the end of that UK day; a timestamp is that instant.","schema":{"type":"string"},"example":"2026-10-31"},{"name":"accountId","in":"query","required":false,"description":"A payment source (card, pot or account activity) id, or a financial account id for all of its sources.","schema":{"type":"string","minLength":1}},{"name":"categoryId","in":"query","required":false,"description":"Only transactions with a line in this category or any category under it (a parent category includes its subcategories, as on the Transactions page).","schema":{"type":"string","minLength":1}},{"name":"payeeId","in":"query","required":false,"description":"Only transactions with a line for this payee or any payee under it (a parent payee includes its sub-payees).","schema":{"type":"string","minLength":1}},{"name":"tagId","in":"query","required":false,"description":"Only transactions carrying this tag.","schema":{"type":"string","minLength":1}},{"name":"kind","in":"query","required":false,"description":"Expense, income or transfer, read from all of a transaction’s lines as the app does.","schema":{"type":"string","enum":["expense","income","transfer"]}},{"name":"minAmountMinor","in":"query","required":false,"description":"Smallest absolute amount in pence, up to 2147483647.","schema":{"type":"integer","minimum":0,"maximum":2147483647}},{"name":"maxAmountMinor","in":"query","required":false,"description":"Largest absolute amount in pence, up to 2147483647.","schema":{"type":"integer","minimum":0,"maximum":2147483647}},{"name":"q","in":"query","required":false,"description":"Text search over the description, notes and item names, with the same AND / OR / NOT, \"quotes\" and accent folding as the Transactions page.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"hasDocuments","in":"query","required":false,"description":"`true` for transactions with documents attached, `false` for those without. Needs the `documents:read` scope and a key for all accounts.","schema":{"type":"string","enum":["0","1","true","false"]}},{"name":"format","in":"query","required":false,"description":"The file format. Only `csv` for now.","schema":{"default":"csv","type":"string","enum":["csv"]}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"text/csv":{"schema":{"type":"string"},"example":"date,transactionId,description,kind,account,category,payee,tags,amount,amountMinor,currency,notes\r\n2026-10-24,txn_1,Weekly shop,expense,Everyday card,Groceries,Corner Market,Household,-42.10,-4210,GBP,\r\n2026-10-23,txn_2,\"Lunch, with Sam\",expense,Everyday card,Eating out,Cafe Nero,,-8.40,-840,GBP,Split the bill\r\n"}}},"400":{"description":"`validation_failed`: More lines match than one file holds; narrow the dates. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden_scope`: `hasDocuments` is used without the `documents:read` scope. The key lacks the `transactions:read` scope; `requiredScope` names it.\n\n`forbidden`: `hasDocuments` or `include=documents` is used by a key limited to some accounts (`reason: account_limit`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/categories":{"get":{"operationId":"getCategories","tags":["categories"],"summary":"List categories","description":"Every category in the order the app shows them (sort order, then name). Categories nest: `parentId` is the group a category sits in, so the whole tree comes back in one page. To keep a copy in step, send `updatedSince`: only categories changed since then come back, archived ones included and flagged.\n\nNeeds the `categories:read` scope.","x-required-scope":"categories:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"archived","in":"query","required":false,"description":"Archived items: `exclude` (default), `include` or `only`. With `updatedSince` the default is `include`, so a change to archived shows.","schema":{"type":"string","enum":["exclude","include","only"]},"example":"exclude"},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The category id."},"name":{"type":"string","description":"The category name."},"parentId":{"description":"The parent category, for a category inside a group; null at the top.","type":["string","null"]},"systemKey":{"description":"Set on the categories the app itself relies on, such as starting balance.","type":["string","null"]},"icon":{"description":"The icon name, if one is set.","type":["string","null"]},"color":{"description":"The colour as a hex code, if one is set.","type":["string","null"]},"notes":{"description":"Free-text notes about what belongs in this category; null when none are set.","type":["string","null"]},"sortOrder":{"type":"integer","description":"Position among its siblings; lower comes first."},"archived":{"type":"boolean","description":"True once it has been archived."},"archivedAt":{"description":"When it was archived, ISO 8601 in UTC; null if it is not archived.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","parentId","systemKey","icon","color","notes","sortOrder","archived","archivedAt","createdAt","updatedAt","version"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"cat_1","name":"Groceries","parentId":"cat_0","systemKey":null,"icon":"shopping-basket","color":"#cc2936","notes":"Weekly supermarket shops; corner shops go under Snacks.","sortOrder":2,"archived":false,"archivedAt":null,"createdAt":"2026-01-04T09:00:00.000Z","updatedAt":"2026-09-12T18:30:00.000Z","version":"1789237800000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postCategories","tags":["categories"],"summary":"Create a category","description":"Creates a category, optionally inside another one. Answers 409 `conflict` when a category with that name already exists under the same parent.\n\nNeeds the `categories:write` scope.","x-required-scope":"categories:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":160,"description":"The category name. Names are unique among categories with the same parent."},"parentId":{"description":"The category to nest it under. Omit or null for a top-level category.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"icon":{"description":"An icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag. Null clears it.","anyOf":[{"type":"string","enum":["store","building","user","globe","shopping-cart","coffee","utensils","home","car","train","heart","briefcase","gift","wallet","tag"]},{"type":"null"}]},"color":{"description":"A six-digit hex colour such as `#cc2936`. Null clears it.","anyOf":[{"type":"string","pattern":"^#[0-9a-f]{6}$"},{"type":"null"}]},"notes":{"description":"Free-text notes about what belongs in this category. Null or blank clears them.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]}},"required":["name"],"additionalProperties":false},"example":{"name":"Groceries","parentId":"cat_0","icon":"shopping-cart","color":"#cc2936"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The category id."},"name":{"type":"string","description":"The category name."},"parentId":{"description":"The parent category, for a category inside a group; null at the top.","type":["string","null"]},"systemKey":{"description":"Set on the categories the app itself relies on, such as starting balance.","type":["string","null"]},"icon":{"description":"The icon name, if one is set.","type":["string","null"]},"color":{"description":"The colour as a hex code, if one is set.","type":["string","null"]},"notes":{"description":"Free-text notes about what belongs in this category; null when none are set.","type":["string","null"]},"sortOrder":{"type":"integer","description":"Position among its siblings; lower comes first."},"archived":{"type":"boolean","description":"True once it has been archived."},"archivedAt":{"description":"When it was archived, ISO 8601 in UTC; null if it is not archived.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","parentId","systemKey","icon","color","notes","sortOrder","archived","archivedAt","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"cat_1","name":"Groceries","parentId":"cat_0","systemKey":null,"icon":"shopping-basket","color":"#cc2936","notes":"Weekly supermarket shops; corner shops go under Snacks.","sortOrder":2,"archived":false,"archivedAt":null,"createdAt":"2026-01-04T09:00:00.000Z","updatedAt":"2026-09-12T18:30:00.000Z","version":"1789237800000"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The `parentId` does not exist or belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: A category with that name already exists under the same parent.\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/categories/{id}":{"get":{"operationId":"getCategoriesById","tags":["categories"],"summary":"Get a category","description":"One category by id, archived or not. `parentId` is the group it sits in (null at the top), and `version` is what to send as `If-Match` when editing it. Another user's id answers 404, the same as an id that does not exist.\n\nNeeds the `categories:read` scope.","x-required-scope":"categories:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The category id.","schema":{"type":"string","minLength":1},"example":"cat_1"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The category id."},"name":{"type":"string","description":"The category name."},"parentId":{"description":"The parent category, for a category inside a group; null at the top.","type":["string","null"]},"systemKey":{"description":"Set on the categories the app itself relies on, such as starting balance.","type":["string","null"]},"icon":{"description":"The icon name, if one is set.","type":["string","null"]},"color":{"description":"The colour as a hex code, if one is set.","type":["string","null"]},"notes":{"description":"Free-text notes about what belongs in this category; null when none are set.","type":["string","null"]},"sortOrder":{"type":"integer","description":"Position among its siblings; lower comes first."},"archived":{"type":"boolean","description":"True once it has been archived."},"archivedAt":{"description":"When it was archived, ISO 8601 in UTC; null if it is not archived.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","parentId","systemKey","icon","color","notes","sortOrder","archived","archivedAt","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"cat_1","name":"Groceries","parentId":"cat_0","systemKey":null,"icon":"shopping-basket","color":"#cc2936","notes":"Weekly supermarket shops; corner shops go under Snacks.","sortOrder":2,"archived":false,"archivedAt":null,"createdAt":"2026-01-04T09:00:00.000Z","updatedAt":"2026-09-12T18:30:00.000Z","version":"1789237800000"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"patchCategoriesById","tags":["categories"],"summary":"Edit or archive a category","description":"Changes the fields you send and leaves the rest. `archived: true` archives the category and everything inside it (system categories cannot be archived); `archived: false` restores only that category, not the ones inside it. Send the `version` you last read as `If-Match` (or in the body): if the category has changed since, the answer is 412 `version_conflict`. Edits are applied first, then the archive change; if the archive change is refused, the edits stay.\n\nNeeds the `categories:write` scope.","x-required-scope":"categories:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The category id.","schema":{"type":"string","minLength":1},"example":"cat_1"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"A new name.","type":"string","minLength":1,"maxLength":160},"parentId":{"description":"Move under this category, or null to make it top-level.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"icon":{"description":"An icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag. Null clears it.","anyOf":[{"type":"string","enum":["store","building","user","globe","shopping-cart","coffee","utensils","home","car","train","heart","briefcase","gift","wallet","tag"]},{"type":"null"}]},"color":{"description":"A six-digit hex colour such as `#cc2936`. Null clears it.","anyOf":[{"type":"string","pattern":"^#[0-9a-f]{6}$"},{"type":"null"}]},"notes":{"description":"Free-text notes about what belongs in this category. Null or blank clears them.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"archived":{"description":"True archives the category and every category inside it; false restores just this one.","type":"boolean"},"version":{"description":"The `version` you last read, as an alternative to the `If-Match` header.","type":"string"}},"additionalProperties":false},"example":{"name":"Food shopping","archived":false}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The category id."},"name":{"type":"string","description":"The category name."},"parentId":{"description":"The parent category, for a category inside a group; null at the top.","type":["string","null"]},"systemKey":{"description":"Set on the categories the app itself relies on, such as starting balance.","type":["string","null"]},"icon":{"description":"The icon name, if one is set.","type":["string","null"]},"color":{"description":"The colour as a hex code, if one is set.","type":["string","null"]},"notes":{"description":"Free-text notes about what belongs in this category; null when none are set.","type":["string","null"]},"sortOrder":{"type":"integer","description":"Position among its siblings; lower comes first."},"archived":{"type":"boolean","description":"True once it has been archived."},"archivedAt":{"description":"When it was archived, ISO 8601 in UTC; null if it is not archived.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","parentId","systemKey","icon","color","notes","sortOrder","archived","archivedAt","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"cat_1","name":"Groceries","parentId":"cat_0","systemKey":null,"icon":"shopping-basket","color":"#cc2936","notes":"Weekly supermarket shops; corner shops go under Snacks.","sortOrder":2,"archived":false,"archivedAt":null,"createdAt":"2026-01-04T09:00:00.000Z","updatedAt":"2026-09-12T18:30:00.000Z","version":"1789237800000"}}}}},"400":{"description":"`validation_failed`: The body is empty, or a system category is being archived. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The `parentId` does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: Another category under the same parent already has that name.\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/rules":{"get":{"operationId":"getRules","tags":["categories"],"summary":"List categorisation rules","description":"The rules that file new transactions and wallet purchases, highest priority first. `matchDescription` is the conditions in words; `payee`, `account` and `amountMatch` give them in parts. Amounts are pence (`amountMinor`, and `amountMaxMinor` for a range) in the absolute value of the transaction. To keep a copy in step, send `updatedSince`: only rules changed since then come back, archived ones included and flagged.\n\nNeeds the `categories:read` scope.","x-required-scope":"categories:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"archived","in":"query","required":false,"description":"Archived items: `exclude` (default), `include` or `only`. With `updatedSince` the default is `include`, so a change to archived shows.","schema":{"type":"string","enum":["exclude","include","only"]},"example":"exclude"},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The rule id."},"name":{"type":"string","description":"The rule name."},"priority":{"type":"integer","description":"Higher numbers win when two rules set the same field."},"enabled":{"type":"boolean","description":"False while the rule is switched off."},"applyMode":{"anyOf":[{"type":"string","enum":["suggest","auto_apply"]},{"type":"null"}],"description":"Null follows the default in Settings."},"autoApproveTrusted":{"type":"boolean","description":"Whether the rule also approves matching items it trusts without asking."},"matchDescription":{"type":"string","description":"The conditions in words, as the Rules page shows them."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee the rule matches, or null when it does not match on payee."},"matchPayeeSubtree":{"type":"boolean","description":"Sub-payees of the payee match too."},"locationPayee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee matched by place rather than by name, or null."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payment source the rule matches."},"amountMatch":{"type":"string","enum":["any","equals","above","below","range"],"description":"How the amount is compared: `any` ignores it."},"amountMinor":{"description":"The amount to compare with, in pence; null when the rule ignores amounts.","type":["integer","null"]},"amountDisplay":{"description":"That amount ready to show.","type":["string","null"]},"amountMaxMinor":{"description":"The upper end, for a range.","type":["integer","null"]},"amountMaxDisplay":{"description":"The upper end of a range, ready to show.","type":["string","null"]},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category the rule files matches under."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"Tags the rule adds."},"archived":{"type":"boolean","description":"True once the rule has been archived."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","priority","enabled","applyMode","autoApproveTrusted","matchDescription","payee","matchPayeeSubtree","locationPayee","account","amountMatch","amountMinor","amountDisplay","amountMaxMinor","amountMaxDisplay","category","tags","archived","createdAt","updatedAt","version"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"rule_1","name":"Corner Market groceries","priority":10,"enabled":true,"applyMode":"suggest","autoApproveTrusted":false,"matchDescription":"Payee Corner Market · Amount at most £80.00","payee":{"id":"pay_1","name":"Corner Market"},"matchPayeeSubtree":false,"locationPayee":null,"account":null,"amountMatch":"below","amountMinor":8000,"amountDisplay":"£80.00","amountMaxMinor":null,"amountMaxDisplay":null,"category":{"id":"cat_1","name":"Groceries"},"tags":[],"archived":false,"createdAt":"2026-03-02T10:00:00.000Z","updatedAt":"2026-03-02T10:00:00.000Z","version":"1772445600000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/payees":{"get":{"operationId":"getPayees","tags":["payees"],"summary":"List payees","description":"Payees by name. `q` finds payees whose name contains the text, ignoring case. `parent` is the payee a branch belongs to; `defaultCategory` is the category new transactions for this payee start with. To keep a copy in step, send `updatedSince`: only payees changed since then come back, archived ones included and flagged. A connected app gets only the payees on income it can read: who pays in, never who you pay.\n\nNeeds the `payees:read` scope.","x-required-scope":"payees:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"archived","in":"query","required":false,"description":"Archived items: `exclude` (default), `include` or `only`. With `updatedSince` the default is `include`, so a change to archived shows.","schema":{"type":"string","enum":["exclude","include","only"]}},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Only payees whose name contains this text.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"market"},{"name":"limit","in":"query","required":false,"description":"Payees per page, 1–200 (50 by default).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"example":"20"},{"name":"cursor","in":"query","required":false,"description":"`page.nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The payee id."},"name":{"type":"string","description":"The payee name."},"kind":{"type":"string","enum":["general","physical","online"],"description":"`general` for any payee, `physical` for a shop with locations, `online` for a web shop."},"transactionType":{"type":"string","enum":["expense","income","both"],"description":"What the payee is used for."},"parent":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee this one is a branch of."},"defaultCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category new transactions with this payee start with, or null."},"icon":{"description":"The icon name, if one is set.","type":["string","null"]},"color":{"description":"The colour as a hex code, if one is set.","type":["string","null"]},"logoUrl":{"description":"Address of its logo image, if it has one.","type":["string","null"]},"websiteUrl":{"description":"Its website address, if set.","type":["string","null"]},"notes":{"description":"Free-text notes.","type":["string","null"]},"archived":{"type":"boolean","description":"True once it has been archived."},"archivedAt":{"description":"When it was archived, ISO 8601 in UTC; null if it is not archived.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","kind","transactionType","parent","defaultCategory","icon","color","logoUrl","websiteUrl","notes","archived","archivedAt","createdAt","updatedAt","version"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"pay_1","name":"Corner Market","kind":"physical","transactionType":"expense","parent":null,"defaultCategory":{"id":"cat_1","name":"Groceries"},"icon":null,"color":null,"logoUrl":null,"websiteUrl":"https://example.com","notes":null,"archived":false,"archivedAt":null,"createdAt":"2026-01-04T09:00:00.000Z","updatedAt":"2026-09-12T18:30:00.000Z","version":"1789237800000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postPayees","tags":["payees"],"summary":"Create a payee","description":"Creates a payee. `transactionType` defaults to `both`. Answers 409 `conflict` when a payee with that name already exists under the same parent.\n\nNeeds the `payees:write` scope.","x-required-scope":"payees:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The payee name. Names are unique among payees with the same parent."},"kind":{"description":"`general` (the default), `physical` (a shop or branch) or `online`.","type":"string","enum":["general","physical","online"]},"transactionType":{"description":"What the payee is used for. Defaults to `both` when creating.","type":"string","enum":["expense","income","both"]},"parentId":{"description":"The payee this one is a branch of. Null makes it top-level.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"defaultCategoryId":{"description":"The category new transactions for this payee start with. Null clears it.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"icon":{"description":"An icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag.","anyOf":[{"type":"string","enum":["store","building","user","globe","shopping-cart","coffee","utensils","home","car","train","heart","briefcase","gift","wallet","tag"]},{"type":"null"}]},"color":{"description":"A six-digit hex colour such as `#cc2936`.","anyOf":[{"type":"string","pattern":"^#[0-9a-f]{6}$"},{"type":"null"}]},"websiteUrl":{"description":"An https:// address without credentials.","anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"notes":{"description":"Free text.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]}},"required":["name"],"additionalProperties":false},"example":{"name":"Corner Market","kind":"physical","transactionType":"expense","defaultCategoryId":"cat_1"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The payee id."},"name":{"type":"string","description":"The payee name."},"kind":{"type":"string","enum":["general","physical","online"],"description":"`general` for any payee, `physical` for a shop with locations, `online` for a web shop."},"transactionType":{"type":"string","enum":["expense","income","both"],"description":"What the payee is used for."},"parent":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee this one is a branch of."},"defaultCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category new transactions with this payee start with, or null."},"icon":{"description":"The icon name, if one is set.","type":["string","null"]},"color":{"description":"The colour as a hex code, if one is set.","type":["string","null"]},"logoUrl":{"description":"Address of its logo image, if it has one.","type":["string","null"]},"websiteUrl":{"description":"Its website address, if set.","type":["string","null"]},"notes":{"description":"Free-text notes.","type":["string","null"]},"archived":{"type":"boolean","description":"True once it has been archived."},"archivedAt":{"description":"When it was archived, ISO 8601 in UTC; null if it is not archived.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","kind","transactionType","parent","defaultCategory","icon","color","logoUrl","websiteUrl","notes","archived","archivedAt","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"pay_1","name":"Corner Market","kind":"physical","transactionType":"expense","parent":null,"defaultCategory":{"id":"cat_1","name":"Groceries"},"icon":null,"color":null,"logoUrl":null,"websiteUrl":"https://example.com","notes":null,"archived":false,"archivedAt":null,"createdAt":"2026-01-04T09:00:00.000Z","updatedAt":"2026-09-12T18:30:00.000Z","version":"1789237800000"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The `parentId` or `defaultCategoryId` does not exist or belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: A payee with that name already exists under the same parent.\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/payees/{id}":{"get":{"operationId":"getPayeesById","tags":["payees"],"summary":"Get a payee","description":"One payee by id, archived or not, with its parent and default category as `{ id, name }` references, and the `version` to send as `If-Match` when editing it. Another user's id answers 404, the same as an id that does not exist.\n\nNeeds the `payees:read` scope.","x-required-scope":"payees:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The payee id.","schema":{"type":"string","minLength":1},"example":"pay_1"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The payee id."},"name":{"type":"string","description":"The payee name."},"kind":{"type":"string","enum":["general","physical","online"],"description":"`general` for any payee, `physical` for a shop with locations, `online` for a web shop."},"transactionType":{"type":"string","enum":["expense","income","both"],"description":"What the payee is used for."},"parent":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee this one is a branch of."},"defaultCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category new transactions with this payee start with, or null."},"icon":{"description":"The icon name, if one is set.","type":["string","null"]},"color":{"description":"The colour as a hex code, if one is set.","type":["string","null"]},"logoUrl":{"description":"Address of its logo image, if it has one.","type":["string","null"]},"websiteUrl":{"description":"Its website address, if set.","type":["string","null"]},"notes":{"description":"Free-text notes.","type":["string","null"]},"archived":{"type":"boolean","description":"True once it has been archived."},"archivedAt":{"description":"When it was archived, ISO 8601 in UTC; null if it is not archived.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","kind","transactionType","parent","defaultCategory","icon","color","logoUrl","websiteUrl","notes","archived","archivedAt","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"pay_1","name":"Corner Market","kind":"physical","transactionType":"expense","parent":null,"defaultCategory":{"id":"cat_1","name":"Groceries"},"icon":null,"color":null,"logoUrl":null,"websiteUrl":"https://example.com","notes":null,"archived":false,"archivedAt":null,"createdAt":"2026-01-04T09:00:00.000Z","updatedAt":"2026-09-12T18:30:00.000Z","version":"1789237800000"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"patchPayeesById","tags":["payees"],"summary":"Edit, archive or restore a payee","description":"Changes the fields you send and leaves the rest. `archived: true` archives the payee and `archived: false` restores it (a payee whose parent is archived cannot be restored first). Changing `kind` of a payee that already has transactions answers 409 `conflict`: do it in the app, which shows what it affects. Send the `version` you last read as `If-Match` (or in the body): if the payee has changed since, the answer is 412 `version_conflict`. Edits are applied first, then the archive change; if the archive change is refused, the edits stay.\n\nNeeds the `payees:write` scope.","x-required-scope":"payees:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The payee id.","schema":{"type":"string","minLength":1},"example":"pay_1"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"A new name.","type":"string","minLength":1,"maxLength":200},"kind":{"description":"`general` (the default), `physical` (a shop or branch) or `online`.","type":"string","enum":["general","physical","online"]},"transactionType":{"description":"What the payee is used for. Defaults to `both` when creating.","type":"string","enum":["expense","income","both"]},"parentId":{"description":"The payee this one is a branch of. Null makes it top-level.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"defaultCategoryId":{"description":"The category new transactions for this payee start with. Null clears it.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"icon":{"description":"An icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag.","anyOf":[{"type":"string","enum":["store","building","user","globe","shopping-cart","coffee","utensils","home","car","train","heart","briefcase","gift","wallet","tag"]},{"type":"null"}]},"color":{"description":"A six-digit hex colour such as `#cc2936`.","anyOf":[{"type":"string","pattern":"^#[0-9a-f]{6}$"},{"type":"null"}]},"websiteUrl":{"description":"An https:// address without credentials.","anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"notes":{"description":"Free text.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"archived":{"description":"True archives the payee (its sub-payees must be archived first); false restores it.","type":"boolean"},"version":{"description":"The `version` you last read, as an alternative to the `If-Match` header.","type":"string"}},"additionalProperties":false},"example":{"name":"Corner Market Ltd","archived":false}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The payee id."},"name":{"type":"string","description":"The payee name."},"kind":{"type":"string","enum":["general","physical","online"],"description":"`general` for any payee, `physical` for a shop with locations, `online` for a web shop."},"transactionType":{"type":"string","enum":["expense","income","both"],"description":"What the payee is used for."},"parent":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee this one is a branch of."},"defaultCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category new transactions with this payee start with, or null."},"icon":{"description":"The icon name, if one is set.","type":["string","null"]},"color":{"description":"The colour as a hex code, if one is set.","type":["string","null"]},"logoUrl":{"description":"Address of its logo image, if it has one.","type":["string","null"]},"websiteUrl":{"description":"Its website address, if set.","type":["string","null"]},"notes":{"description":"Free-text notes.","type":["string","null"]},"archived":{"type":"boolean","description":"True once it has been archived."},"archivedAt":{"description":"When it was archived, ISO 8601 in UTC; null if it is not archived.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","kind","transactionType","parent","defaultCategory","icon","color","logoUrl","websiteUrl","notes","archived","archivedAt","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"pay_1","name":"Corner Market","kind":"physical","transactionType":"expense","parent":null,"defaultCategory":{"id":"cat_1","name":"Groceries"},"icon":null,"color":null,"logoUrl":null,"websiteUrl":"https://example.com","notes":null,"archived":false,"archivedAt":null,"createdAt":"2026-01-04T09:00:00.000Z","updatedAt":"2026-09-12T18:30:00.000Z","version":"1789237800000"}}}}},"400":{"description":"`validation_failed`: The body is empty, a payee is archived while its branches are not, or one is restored under an archived parent. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The `parentId` or `defaultCategoryId` does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: Another payee under the same parent has that name, or `kind` changes on a payee that already has transactions.\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/tags":{"get":{"operationId":"getTags","tags":["tags"],"summary":"List tags","description":"Every tag by name, with how many transactions carry it. Use a tag’s id as `tagId` on `/transactions`. To keep a copy in step, send `updatedSince`: only tags renamed or created since then come back. Tags are hard-deleted, so a deleted tag does not appear (list the ids to find it), and tagging a transaction changes `transactionCount` without making the tag count as changed. Every tag is listed for a key limited to some accounts too, but `transactionCount` only counts the transactions it can list.\n\nNeeds the `tags:read` scope.","x-required-scope":"tags:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The tag id."},"name":{"type":"string","description":"The tag name."},"transactionCount":{"type":"integer","description":"How many transactions carry the tag (for a key limited to some accounts, how many of those it can list)."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","transactionCount","createdAt","updatedAt","version"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"tag_1","name":"Household","transactionCount":14,"createdAt":"2026-02-01T09:00:00.000Z","updatedAt":"2026-02-01T09:00:00.000Z","version":"1769936400000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postTags","tags":["tags"],"summary":"Create a tag","description":"Creates a tag. Answers 409 `conflict` when a tag with that name already exists.\n\nNeeds the `tags:write` scope.","x-required-scope":"tags:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"The tag name, up to 80 characters. Names are unique, ignoring case."}},"required":["name"],"additionalProperties":false},"example":{"name":"Household"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The tag id."},"name":{"type":"string","description":"The tag name."},"transactionCount":{"type":"integer","description":"How many transactions carry the tag (for a key limited to some accounts, how many of those it can list)."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","transactionCount","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"tag_1","name":"Household","transactionCount":0,"createdAt":"2026-02-01T09:00:00.000Z","updatedAt":"2026-02-01T09:00:00.000Z","version":"1769936400000"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"`conflict`: A tag with that name already exists (names compare without regard to case).\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/tags/{id}":{"get":{"operationId":"getTagsById","tags":["tags"],"summary":"Get a tag","description":"One tag by id, with how many transactions carry it, and the `version` to send as `If-Match` when renaming or deleting it (also sent as the `ETag` header). Another user's id answers 404, the same as an id that does not exist.\n\nNeeds the `tags:read` scope.","x-required-scope":"tags:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The tag id.","schema":{"type":"string","minLength":1},"example":"tag_1"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The tag id."},"name":{"type":"string","description":"The tag name."},"transactionCount":{"type":"integer","description":"How many transactions carry the tag (for a key limited to some accounts, how many of those it can list)."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","transactionCount","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"tag_1","name":"Household","transactionCount":14,"createdAt":"2026-02-01T09:00:00.000Z","updatedAt":"2026-02-01T09:00:00.000Z","version":"1769936400000"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"patchTagsById","tags":["tags"],"summary":"Rename a tag","description":"Renames the tag; every transaction that carries it follows. Send the `version` you last read as `If-Match` (or in the body): if the tag has changed since, the answer is 412 `version_conflict`.\n\nNeeds the `tags:write` scope.","x-required-scope":"tags:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The tag id.","schema":{"type":"string","minLength":1},"example":"tag_1"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"The tag name, up to 80 characters. Names are unique, ignoring case."},"version":{"description":"The `version` you last read, as an alternative to the `If-Match` header.","type":"string"}},"required":["name"],"additionalProperties":false},"example":{"name":"Home"}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The tag id."},"name":{"type":"string","description":"The tag name."},"transactionCount":{"type":"integer","description":"How many transactions carry the tag (for a key limited to some accounts, how many of those it can list)."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or deleting it, to avoid overwriting a newer change."}},"required":["id","name","transactionCount","createdAt","updatedAt","version"],"additionalProperties":false}}},"example":{"data":{"id":"tag_1","name":"Home","transactionCount":14,"createdAt":"2026-02-01T09:00:00.000Z","updatedAt":"2026-02-01T09:00:00.000Z","version":"1769936400000"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`conflict`: Another tag already has that name.\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"deleteTagsById","tags":["tags"],"summary":"Delete a tag","description":"Deletes the tag and removes it from every transaction and rule that carries it; the transactions and rules themselves are untouched. The API has no undo: for 30 days the tag can be put back in the app, from Settings › Clean Up. Send the `version` you last read as `If-Match` to refuse the delete if the tag has changed since (412 `version_conflict`). A key limited to some accounts may only delete a tag whose transactions are all on its accounts; otherwise the answer is 403 `forbidden` (`reason: account_limit`).\n\nNeeds the `tags:delete` scope.","x-required-scope":"tags:delete","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The tag id.","schema":{"type":"string","minLength":1},"example":"tag_1"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"responses":{"204":{"description":"Done. There is no body.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and the tag is on a transaction with a line on another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `tags:delete` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/bills/upcoming":{"get":{"operationId":"getBillsUpcoming","tags":["bills"],"summary":"What is due soon","description":"Recurring bills and one-off scheduled items merged into one list by due day, the same list as the Upcoming page. Anything overdue is included, however old. Amounts are the size of the payment (always positive); `direction` says whether it is money out, in or moved. `covered` says whether the account is projected to hold enough on the day, after everything due before it. The coverage `available` and `shortfall` amounts are account balances, so they are null unless the key can also read accounts; `covered` and the coverage `status` are always given. Reads the first 500 items due in the window; when more than that fall in it, `meta.truncated` is true (ask for fewer `days`).\n\nNeeds the `bills:read` scope.","x-required-scope":"bills:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"days","in":"query","required":false,"description":"How many days ahead to look, 1 to 366.","schema":{"default":30,"type":"integer","minimum":1,"maximum":366},"example":"14"},{"name":"limit","in":"query","required":false,"description":"Items per page, 1 to 200.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["recurring","scheduled"],"description":"`recurring` for an occurrence of a repeating bill, `scheduled` for a one-off scheduled item."},"id":{"type":"string","description":"The occurrence id (recurring) or the scheduled item id."},"seriesId":{"description":"The recurring series it belongs to; null for a scheduled item.","type":["string","null"]},"name":{"type":"string","description":"What the bill is called."},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved"],"description":"`pending` waits for you to post it; `pre_approved` will be posted on its day."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"Transfers only: where the money goes."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"covered":{"description":"Will the account hold enough on the day? Null when there is nothing to judge (income, no account).","type":["boolean","null"]},"coverage":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["covered","short","unknown"],"description":"`covered` when the account will hold enough on the day, `short` when it will not, `unknown` when that cannot be judged."},"account":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The financial account the money comes out of.","additionalProperties":false},"availableMinor":{"description":"Available, in whole pence; null when there is none.","type":["integer","null"]},"availableDisplay":{"description":"Available, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"requiredMinor":{"type":"integer","description":"Required, in whole pence."},"requiredDisplay":{"type":"string","description":"Required, ready to show, such as £12.50."},"shortfallMinor":{"description":"Shortfall, in whole pence; null when there is none.","type":["integer","null"]},"shortfallDisplay":{"description":"Shortfall, ready to show, such as £12.50; null when there is none.","type":["string","null"]}},"required":["status","account","availableMinor","availableDisplay","requiredMinor","requiredDisplay","shortfallMinor","shortfallDisplay"],"additionalProperties":false},{"type":"null"}],"description":"How well the account covers it, or null when there is nothing to judge."},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["type","id","seriesId","name","direction","dueOn","status","account","counterAccount","category","payee","covered","coverage","amountMinor","amountDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"type":"recurring","id":"occ_1","seriesId":"ser_1","name":"Broadband","direction":"expense","dueOn":"2026-11-02","status":"pending","amountMinor":3299,"amountDisplay":"£32.99","account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_1","name":"Bills"},"payee":{"id":"pay_1","name":"Fibre Co"},"covered":true,"coverage":{"status":"covered","account":{"id":"acc_1","name":"Everyday account"},"availableMinor":184050,"availableDisplay":"£1,840.50","requiredMinor":3299,"requiredDisplay":"£32.99","shortfallMinor":0,"shortfallDisplay":"£0.00"}}],"page":{"nextCursor":null,"hasMore":false}}}}},"400":{"description":"`validation_failed`: `days` is outside 1 to 366, or the `cursor` is not one a previous page gave. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/recurring":{"get":{"operationId":"getRecurring","tags":["bills"],"summary":"Recurring bills and income","description":"Recurring series: the bills, subscriptions, income and transfers that repeat. By default the active and paused ones. `expectedAmount` is the usual size of one payment (positive; `direction` says which way it goes). To keep a copy in step, send `updatedSince`: only series changed since then come back, whatever their status, so one that ended shows with `status: ended`.\n\nNeeds the `bills:read` scope.","x-required-scope":"bills:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Comma-separated: active, paused, ended, suggested, dismissed. Default `active,paused`, or all of them with `updatedSince`.","schema":{"type":"string"}},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The series id."},"name":{"type":"string","description":"What the series is called."},"status":{"type":"string","enum":["active","paused","ended","suggested","dismissed"],"description":"Whether it is running: `active`, `paused`, `ended`, or `suggested` / `dismissed` for ones spotted from your transactions."},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"cadence":{"type":"string","enum":["weekly","fortnightly","four_weekly","monthly","quarterly","yearly","custom"],"description":"How often it repeats."},"anchorDay":{"type":"integer","description":"Weekday (0 = Sunday) for weekly cadences, day of the month otherwise."},"anchorMonth":{"description":"Yearly series only.","type":["integer","null"]},"intervalDays":{"description":"Custom cadence only: every N days.","type":["integer","null"]},"nextDueOn":{"description":"The next day it falls due, YYYY-MM-DD; null when it has ended.","type":["string","null"]},"lastPostedOn":{"description":"The last day an occurrence was posted, YYYY-MM-DD, or null.","type":["string","null"]},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its default category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"notes":{"description":"Free-text notes.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing the series."},"expectedAmountMinor":{"type":"integer","description":"Expected amount, in whole pence."},"expectedAmountDisplay":{"type":"string","description":"Expected amount, ready to show, such as £12.50."}},"required":["id","name","status","direction","cadence","anchorDay","anchorMonth","intervalDays","nextDueOn","lastPostedOn","account","counterAccount","category","payee","remindDaysBefore","notes","version","expectedAmountMinor","expectedAmountDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"ser_1","name":"Broadband","status":"active","direction":"expense","cadence":"monthly","anchorDay":2,"anchorMonth":null,"intervalDays":null,"expectedAmountMinor":3299,"expectedAmountDisplay":"£32.99","nextDueOn":"2026-11-02","lastPostedOn":"2026-10-02","account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_1","name":"Bills"},"payee":{"id":"pay_1","name":"Fibre Co"},"remindDaysBefore":3,"notes":null,"version":"1793000000000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postRecurring","tags":["bills"],"summary":"Create a recurring bill or income","description":"Creates a repeating series and its upcoming occurrences (nothing is posted to the ledger). Say when it repeats with `cadence` and either `startOn` (the first due day; the weekday or day of the month is taken from it) or an explicit `anchorDay`. A custom cadence needs `intervalDays`; a transfer needs `counterAccountId`. A category is required (except for a transfer); set a payee too so occurrences can be posted.\n\nNeeds the `bills:write` scope.","x-required-scope":"bills:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"What it is, such as “Broadband”."},"direction":{"description":"`expense` (the default), `income` or `transfer`.","type":"string","enum":["expense","income","transfer"]},"cadence":{"type":"string","enum":["weekly","fortnightly","four_weekly","monthly","quarterly","yearly","custom"],"description":"How often it repeats."},"anchorDay":{"type":"integer","description":"Weekday (0 = Sunday to 6) for weekly, fortnightly and four-weekly cadences; day of the month (1 to 31) for the rest. Worked out from `startOn` when left out."},"anchorMonth":{"anyOf":[{"type":"integer","minimum":1,"maximum":12},{"type":"null"}],"description":"Yearly cadence only: the month, 1 to 12. Worked out from `startOn` when left out."},"intervalDays":{"anyOf":[{"type":"integer","minimum":1,"maximum":365},{"type":"null"}],"description":"Custom cadence only, and required for it: repeat every this many days."},"startOn":{"description":"The first day it can fall due (default today). Its first due day is the first one on or after this. `YYYY-MM-DD`.","type":"string"},"expectedAmountMinor":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647,"description":"The usual amount of one payment, in pence, always positive."},"accountId":{"type":"string","minLength":1,"description":"The account it is paid from (or into, for income). A payment source id (the `account` of a bill), not a financial account id."},"counterAccountId":{"description":"Transfers only, and required for them: the account the money goes into.","type":"string","minLength":1},"categoryId":{"description":"The category payments are posted under. Required for an expense or income; a transfer is filed under Transfer.","type":"string","minLength":1},"payeeId":{"description":"The payee payments are posted under. Needed before an occurrence can be posted.","type":"string","minLength":1},"remindDaysBefore":{"description":"Remind this many days before each is due, 0 to 30 (default 3).","type":"integer","minimum":0,"maximum":30},"notes":{"description":"Free-text notes.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]}},"required":["name","cadence","expectedAmountMinor","accountId"],"additionalProperties":false},"example":{"name":"Broadband","cadence":"monthly","startOn":"2026-11-02","expectedAmountMinor":3299,"accountId":"src_1","categoryId":"cat_1","payeeId":"pay_1"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The series id."},"name":{"type":"string","description":"What the series is called."},"status":{"type":"string","enum":["active","paused","ended","suggested","dismissed"],"description":"Whether it is running: `active`, `paused`, `ended`, or `suggested` / `dismissed` for ones spotted from your transactions."},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"cadence":{"type":"string","enum":["weekly","fortnightly","four_weekly","monthly","quarterly","yearly","custom"],"description":"How often it repeats."},"anchorDay":{"type":"integer","description":"Weekday (0 = Sunday) for weekly cadences, day of the month otherwise."},"anchorMonth":{"description":"Yearly series only.","type":["integer","null"]},"intervalDays":{"description":"Custom cadence only: every N days.","type":["integer","null"]},"nextDueOn":{"description":"The next day it falls due, YYYY-MM-DD; null when it has ended.","type":["string","null"]},"lastPostedOn":{"description":"The last day an occurrence was posted, YYYY-MM-DD, or null.","type":["string","null"]},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its default category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"notes":{"description":"Free-text notes.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing the series."},"expectedAmountMinor":{"type":"integer","description":"Expected amount, in whole pence."},"expectedAmountDisplay":{"type":"string","description":"Expected amount, ready to show, such as £12.50."},"upcomingOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Pending and pre-approved, soonest first."},"recentOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The last 12 posted, skipped or cancelled, newest first."}},"required":["id","name","status","direction","cadence","anchorDay","anchorMonth","intervalDays","nextDueOn","lastPostedOn","account","counterAccount","category","payee","remindDaysBefore","notes","version","expectedAmountMinor","expectedAmountDisplay","upcomingOccurrences","recentOccurrences"],"additionalProperties":false}}},"example":{"data":{"id":"ser_1","name":"Broadband","status":"active","direction":"expense","cadence":"monthly","anchorDay":2,"anchorMonth":null,"intervalDays":null,"expectedAmountMinor":3299,"expectedAmountDisplay":"£32.99","nextDueOn":"2026-11-02","lastPostedOn":null,"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_1","name":"Bills"},"payee":{"id":"pay_1","name":"Fibre Co"},"remindDaysBefore":3,"notes":null,"version":"1793000000000","upcomingOccurrences":[{"id":"occ_1","dueOn":"2026-11-02","status":"pending","description":"Broadband","amountMinor":3299,"amountDisplay":"£32.99","transactionId":null,"postedAt":null}],"recentOccurrences":[]}}}}},"400":{"description":"`validation_failed`: A custom cadence has no `intervalDays`, a transfer has no `counterAccountId`, or an expense or income has no `categoryId`. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `bills:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: An account, category or payee in the body does not exist or belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/recurring/{id}":{"get":{"operationId":"getRecurringById","tags":["bills"],"summary":"One recurring series","description":"The series with its upcoming occurrences and the twelve most recent finished ones. An occurrence `amount` is the planned size; `transactionId` is the ledger transaction once it has been posted (null unless the key can read transactions).\n\nNeeds the `bills:read` scope.","x-required-scope":"bills:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string","minLength":1},"example":"ser_1"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The series id."},"name":{"type":"string","description":"What the series is called."},"status":{"type":"string","enum":["active","paused","ended","suggested","dismissed"],"description":"Whether it is running: `active`, `paused`, `ended`, or `suggested` / `dismissed` for ones spotted from your transactions."},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"cadence":{"type":"string","enum":["weekly","fortnightly","four_weekly","monthly","quarterly","yearly","custom"],"description":"How often it repeats."},"anchorDay":{"type":"integer","description":"Weekday (0 = Sunday) for weekly cadences, day of the month otherwise."},"anchorMonth":{"description":"Yearly series only.","type":["integer","null"]},"intervalDays":{"description":"Custom cadence only: every N days.","type":["integer","null"]},"nextDueOn":{"description":"The next day it falls due, YYYY-MM-DD; null when it has ended.","type":["string","null"]},"lastPostedOn":{"description":"The last day an occurrence was posted, YYYY-MM-DD, or null.","type":["string","null"]},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its default category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"notes":{"description":"Free-text notes.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing the series."},"expectedAmountMinor":{"type":"integer","description":"Expected amount, in whole pence."},"expectedAmountDisplay":{"type":"string","description":"Expected amount, ready to show, such as £12.50."},"upcomingOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Pending and pre-approved, soonest first."},"recentOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The last 12 posted, skipped or cancelled, newest first."}},"required":["id","name","status","direction","cadence","anchorDay","anchorMonth","intervalDays","nextDueOn","lastPostedOn","account","counterAccount","category","payee","remindDaysBefore","notes","version","expectedAmountMinor","expectedAmountDisplay","upcomingOccurrences","recentOccurrences"],"additionalProperties":false}}},"example":{"data":{"id":"ser_1","name":"Broadband","status":"active","direction":"expense","cadence":"monthly","anchorDay":2,"anchorMonth":null,"intervalDays":null,"expectedAmountMinor":3299,"expectedAmountDisplay":"£32.99","nextDueOn":"2026-11-02","lastPostedOn":null,"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_1","name":"Bills"},"payee":{"id":"pay_1","name":"Fibre Co"},"remindDaysBefore":3,"notes":null,"version":"1793000000000","upcomingOccurrences":[{"id":"occ_1","dueOn":"2026-11-02","status":"pending","description":"Broadband","amountMinor":3299,"amountDisplay":"£32.99","transactionId":null,"postedAt":null}],"recentOccurrences":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"patchRecurringById","tags":["bills"],"summary":"Change a recurring series","description":"Changes the series’ name, amount, accounts, category, payee, reminders or notes, and its cadence and anchor; send only the fields to change. A new amount or schedule replaces the future occurrences that follow the series; customised or pre-approved ones are kept and block a schedule change (400 with the reason). Send the `version` you read as `If-Match` (or in the body): if the series changed since, the answer is 412. An ended or dismissed series cannot be edited.\n\nNeeds the `bills:write` scope.","x-required-scope":"bills:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string","minLength":1},"example":"ser_1"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"A new name.","type":"string","minLength":1,"maxLength":200},"direction":{"description":"A new direction. Not allowed while customised or pre-approved payments are still to come.","type":"string","enum":["expense","income","transfer"]},"cadence":{"description":"A new cadence. Open, uncustomised future occurrences are regenerated; customised or pre-approved ones block it (409-style 400).","type":"string","enum":["weekly","fortnightly","four_weekly","monthly","quarterly","yearly","custom"]},"anchorDay":{"type":"integer","description":"Weekday (0 = Sunday to 6) for weekly, fortnightly and four-weekly cadences; day of the month (1 to 31) for the rest. Worked out from `startOn` when left out."},"anchorMonth":{"anyOf":[{"type":"integer","minimum":1,"maximum":12},{"type":"null"}],"description":"Yearly cadence only: the month, 1 to 12. Worked out from `startOn` when left out."},"intervalDays":{"anyOf":[{"type":"integer","minimum":1,"maximum":365},{"type":"null"}],"description":"Custom cadence only, and required for it: repeat every this many days."},"expectedAmountMinor":{"description":"A new usual amount in pence, always positive. Applies to occurrences not yet customised.","type":"integer","exclusiveMinimum":0,"maximum":2147483647},"accountId":{"description":"A new account. A payment source id (the `account` of a bill), not a financial account id.","type":"string","minLength":1},"counterAccountId":{"description":"Transfers only: a new account the money goes into.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"categoryId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A new default category. Null clears it."},"payeeId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A new default payee. Null clears it."},"remindDaysBefore":{"type":"integer","minimum":0,"maximum":30,"description":"Send a reminder this many days before it is due, 0 to 30."},"notes":{"description":"New notes. Null clears them.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"version":{"description":"The `version` you last read. The same as sending `If-Match`; if the item has changed since, the answer is 412.","type":["string","integer"]}},"additionalProperties":false},"example":{"expectedAmountMinor":3499}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The series id."},"name":{"type":"string","description":"What the series is called."},"status":{"type":"string","enum":["active","paused","ended","suggested","dismissed"],"description":"Whether it is running: `active`, `paused`, `ended`, or `suggested` / `dismissed` for ones spotted from your transactions."},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"cadence":{"type":"string","enum":["weekly","fortnightly","four_weekly","monthly","quarterly","yearly","custom"],"description":"How often it repeats."},"anchorDay":{"type":"integer","description":"Weekday (0 = Sunday) for weekly cadences, day of the month otherwise."},"anchorMonth":{"description":"Yearly series only.","type":["integer","null"]},"intervalDays":{"description":"Custom cadence only: every N days.","type":["integer","null"]},"nextDueOn":{"description":"The next day it falls due, YYYY-MM-DD; null when it has ended.","type":["string","null"]},"lastPostedOn":{"description":"The last day an occurrence was posted, YYYY-MM-DD, or null.","type":["string","null"]},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its default category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"notes":{"description":"Free-text notes.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing the series."},"expectedAmountMinor":{"type":"integer","description":"Expected amount, in whole pence."},"expectedAmountDisplay":{"type":"string","description":"Expected amount, ready to show, such as £12.50."},"upcomingOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Pending and pre-approved, soonest first."},"recentOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The last 12 posted, skipped or cancelled, newest first."}},"required":["id","name","status","direction","cadence","anchorDay","anchorMonth","intervalDays","nextDueOn","lastPostedOn","account","counterAccount","category","payee","remindDaysBefore","notes","version","expectedAmountMinor","expectedAmountDisplay","upcomingOccurrences","recentOccurrences"],"additionalProperties":false}}},"example":{"data":{"id":"ser_1","name":"Broadband","status":"active","direction":"expense","cadence":"monthly","anchorDay":2,"anchorMonth":null,"intervalDays":null,"expectedAmountMinor":3499,"expectedAmountDisplay":"£34.99","nextDueOn":"2026-11-02","lastPostedOn":null,"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_1","name":"Bills"},"payee":{"id":"pay_1","name":"Fibre Co"},"remindDaysBefore":3,"notes":null,"version":"1793000000000","upcomingOccurrences":[{"id":"occ_1","dueOn":"2026-11-02","status":"pending","description":"Broadband","amountMinor":3299,"amountDisplay":"£32.99","transactionId":null,"postedAt":null}],"recentOccurrences":[]}}}}},"400":{"description":"`validation_failed`: The body is empty, the series has ended or been dismissed, or customised or pre-approved occurrences block a schedule change. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `bills:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: An account, category or payee in the body does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/scheduled":{"get":{"operationId":"getScheduled","tags":["bills"],"summary":"Scheduled one-off items","description":"One-off payments and income you have scheduled, by due day. By default the ones still to happen (pending and pre-approved); ask for `posted` or `cancelled` to see history. `amount` is the size of the payment (positive; `direction` says which way). To keep a copy in step, send `updatedSince`: only items changed since then come back, whatever their status, so one that was posted or cancelled shows with that status.\n\nNeeds the `bills:read` scope.","x-required-scope":"bills:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Comma-separated: pending, pre_approved, posted, cancelled. Default `pending,pre_approved`, or all of them with `updatedSince`.","schema":{"type":"string"}},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1 to 200.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The scheduled item id."},"name":{"type":"string","description":"What the item is called."},"notes":{"description":"Free-text notes.","type":["string","null"]},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction or cancelled."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"lines":{"type":"array","items":{"type":"object","properties":{"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the line moves money in or out of, or null."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"itemName":{"description":"What is bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many are bought, when the line says.","type":["number","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["account","category","payee","kind","itemName","quantity","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The lines of the transaction it becomes."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or cancelling the item."},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","name","notes","direction","dueOn","status","account","counterAccount","category","payee","lines","remindDaysBefore","transactionId","postedAt","createdAt","version","amountMinor","amountDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"sch_1","name":"Car service","notes":null,"direction":"expense","dueOn":"2026-11-14","status":"pending","amountMinor":18900,"amountDisplay":"£189.00","account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"lines":[{"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"kind":"item","itemName":null,"quantity":null,"amountMinor":-18900,"amountDisplay":"-£189.00"}],"remindDaysBefore":3,"transactionId":null,"postedAt":null,"createdAt":"2026-10-20T09:00:00.000Z","version":"1793000000000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postScheduled","tags":["bills"],"summary":"Schedule a one-off payment","description":"Schedules a payment or income for a day. Nothing is posted to the ledger until the item is posted (`POST /scheduled/{id}/post`) or, with `autoPost`, its due day arrives; if `autoPost` is true and the due day is today or earlier it is posted to the ledger straight away and the answer has its `transactionId`. Send the amount as positive pence and the `direction`; a transfer also needs `counterAccountId`.\n\nNeeds the `bills:write` scope.","x-required-scope":"bills:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":2000,"description":"What it is, such as “Car service”. Becomes the transaction description when it posts."},"dueOn":{"description":"The day it is due. `YYYY-MM-DD`.","type":"string"},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"`expense` is money out, `income` money in, `transfer` between two of your accounts."},"amountMinor":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647,"description":"The amount in pence, always positive; `direction` says which way it goes."},"accountId":{"type":"string","minLength":1,"description":"The account the money comes out of (or goes into, for income). A payment source id (the `account` of a bill), not a financial account id."},"counterAccountId":{"description":"Transfers only, and required for them: the account the money goes into.","type":"string","minLength":1},"categoryId":{"description":"The category to post it under. Required for an expense or income; a transfer is filed under Transfer.","type":"string","minLength":1},"payeeId":{"description":"The payee to post it under.","type":"string","minLength":1},"notes":{"description":"Free-text notes.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"autoPost":{"description":"Post it to the ledger by itself on the due day (default false). If the due day is today or past, it posts straight away.","type":"boolean"},"remindDaysBefore":{"type":"integer","minimum":0,"maximum":30,"description":"Send a reminder this many days before it is due, 0 to 30."}},"required":["description","dueOn","direction","amountMinor","accountId"],"additionalProperties":false},"example":{"description":"Car service","dueOn":"2026-11-14","direction":"expense","amountMinor":18900,"accountId":"src_1","categoryId":"cat_2","payeeId":"pay_2","remindDaysBefore":3}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The scheduled item id."},"name":{"type":"string","description":"What the item is called."},"notes":{"description":"Free-text notes.","type":["string","null"]},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction or cancelled."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"lines":{"type":"array","items":{"type":"object","properties":{"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the line moves money in or out of, or null."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"itemName":{"description":"What is bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many are bought, when the line says.","type":["number","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["account","category","payee","kind","itemName","quantity","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The lines of the transaction it becomes."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or cancelling the item."},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","name","notes","direction","dueOn","status","account","counterAccount","category","payee","lines","remindDaysBefore","transactionId","postedAt","createdAt","version","amountMinor","amountDisplay"],"additionalProperties":false}}},"example":{"data":{"id":"sch_1","name":"Car service","notes":null,"direction":"expense","dueOn":"2026-11-14","status":"pending","amountMinor":18900,"amountDisplay":"£189.00","account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"lines":[{"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"kind":"item","itemName":null,"quantity":null,"amountMinor":-18900,"amountDisplay":"-£189.00"}],"remindDaysBefore":3,"transactionId":null,"postedAt":null,"createdAt":"2026-10-20T09:00:00.000Z","version":"1793000000000"}}}}},"400":{"description":"`validation_failed`: A transfer has no `counterAccountId`, or an expense or income has no `categoryId`. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `bills:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: An account, category or payee in the body does not exist or belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/scheduled/{id}":{"get":{"operationId":"getScheduledById","tags":["bills"],"summary":"One scheduled item","description":"A scheduled item with its lines. `transactionId` is set once it has been posted to the ledger, and only when the key can read transactions.\n\nNeeds the `bills:read` scope.","x-required-scope":"bills:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string","minLength":1},"example":"sch_1"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The scheduled item id."},"name":{"type":"string","description":"What the item is called."},"notes":{"description":"Free-text notes.","type":["string","null"]},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction or cancelled."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"lines":{"type":"array","items":{"type":"object","properties":{"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the line moves money in or out of, or null."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"itemName":{"description":"What is bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many are bought, when the line says.","type":["number","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["account","category","payee","kind","itemName","quantity","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The lines of the transaction it becomes."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or cancelling the item."},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","name","notes","direction","dueOn","status","account","counterAccount","category","payee","lines","remindDaysBefore","transactionId","postedAt","createdAt","version","amountMinor","amountDisplay"],"additionalProperties":false}}},"example":{"data":{"id":"sch_1","name":"Car service","notes":null,"direction":"expense","dueOn":"2026-11-14","status":"pending","amountMinor":18900,"amountDisplay":"£189.00","account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"lines":[{"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"kind":"item","itemName":null,"quantity":null,"amountMinor":-18900,"amountDisplay":"-£189.00"}],"remindDaysBefore":3,"transactionId":null,"postedAt":null,"createdAt":"2026-10-20T09:00:00.000Z","version":"1793000000000"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"patchScheduledById","tags":["bills"],"summary":"Change a scheduled item","description":"Changes an item that has not been posted or cancelled; send only the fields to change. Send the `version` you read as `If-Match` (or in the body): if the item changed since, the answer is 412. The amount, accounts, category and payee can be changed this way only on a plain item (one line, or a transfer’s pair); a split item answers 409. Turning `autoPost` on for a day that is today or earlier posts it at once.\n\nNeeds the `bills:write` scope.","x-required-scope":"bills:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string","minLength":1},"example":"sch_1"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"description":"A new description.","type":"string","minLength":1,"maxLength":2000},"dueOn":{"description":"A new due day. `YYYY-MM-DD`.","type":"string"},"amountMinor":{"description":"A new amount in pence, always positive.","type":"integer","exclusiveMinimum":0,"maximum":2147483647},"accountId":{"description":"A new account. A payment source id (the `account` of a bill), not a financial account id.","type":"string","minLength":1},"counterAccountId":{"description":"Transfers only: a new account the money goes into.","type":"string","minLength":1},"categoryId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A new category. Null clears it."},"payeeId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A new payee. Null clears it."},"notes":{"description":"New notes. Null clears them.","anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"autoPost":{"description":"Turn automatic posting on or off.","type":"boolean"},"remindDaysBefore":{"type":"integer","minimum":0,"maximum":30,"description":"Send a reminder this many days before it is due, 0 to 30."},"version":{"description":"The `version` you last read. The same as sending `If-Match`; if the item has changed since, the answer is 412.","type":["string","integer"]}},"additionalProperties":false},"example":{"dueOn":"2026-11-20","amountMinor":20500}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The scheduled item id."},"name":{"type":"string","description":"What the item is called."},"notes":{"description":"Free-text notes.","type":["string","null"]},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction or cancelled."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"lines":{"type":"array","items":{"type":"object","properties":{"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the line moves money in or out of, or null."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"itemName":{"description":"What is bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many are bought, when the line says.","type":["number","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["account","category","payee","kind","itemName","quantity","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The lines of the transaction it becomes."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or cancelling the item."},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","name","notes","direction","dueOn","status","account","counterAccount","category","payee","lines","remindDaysBefore","transactionId","postedAt","createdAt","version","amountMinor","amountDisplay"],"additionalProperties":false}}},"example":{"data":{"id":"sch_1","name":"Car service","notes":null,"direction":"expense","dueOn":"2026-11-14","status":"pending","amountMinor":18900,"amountDisplay":"£189.00","account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"lines":[{"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"kind":"item","itemName":null,"quantity":null,"amountMinor":-18900,"amountDisplay":"-£189.00"}],"remindDaysBefore":3,"transactionId":null,"postedAt":null,"createdAt":"2026-10-20T09:00:00.000Z","version":"1793000000000"}}}}},"400":{"description":"`validation_failed`: The body is empty, or the item is already posted or cancelled. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `bills:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: An account, category or payee in the body does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: The item is split across several lines (`reason: multiple_lines`), so it cannot be changed field by field.\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/scheduled/{id}/post":{"post":{"operationId":"postScheduledByIdPost","tags":["bills"],"summary":"Post a scheduled item to the ledger","description":"Posts the item now, even before its due day, as a real transaction. The answer is the scheduled item, now `posted`, with the new `transactionId`. Send `amountMinor` or `date` to post a different amount or date than scheduled (the amount only on a plain, single-line item). An item that is already posted or cancelled cannot be posted.\n\nNeeds the `bills:write` scope.","x-required-scope":"bills:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string","minLength":1},"example":"sch_1"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"description":"The transaction date to post it under (default: the day it was scheduled for). `YYYY-MM-DD`.","type":"string"},"amountMinor":{"description":"Post a different amount (in pence, positive) than the one scheduled.","type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"additionalProperties":false},"example":{"date":"2026-11-14","amountMinor":18900}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The scheduled item id."},"name":{"type":"string","description":"What the item is called."},"notes":{"description":"Free-text notes.","type":["string","null"]},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction or cancelled."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"lines":{"type":"array","items":{"type":"object","properties":{"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the line moves money in or out of, or null."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"itemName":{"description":"What is bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many are bought, when the line says.","type":["number","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["account","category","payee","kind","itemName","quantity","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The lines of the transaction it becomes."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or cancelling the item."},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","name","notes","direction","dueOn","status","account","counterAccount","category","payee","lines","remindDaysBefore","transactionId","postedAt","createdAt","version","amountMinor","amountDisplay"],"additionalProperties":false}}},"example":{"data":{"id":"sch_1","name":"Car service","notes":null,"direction":"expense","dueOn":"2026-11-14","status":"posted","amountMinor":18900,"amountDisplay":"£189.00","account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"lines":[{"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"kind":"item","itemName":null,"quantity":null,"amountMinor":-18900,"amountDisplay":"-£189.00"}],"remindDaysBefore":3,"transactionId":"txn_1","postedAt":"2026-11-14T08:00:00.000Z","createdAt":"2026-10-20T09:00:00.000Z","version":"1793000000000"}}}}},"400":{"description":"`validation_failed`: The item is already posted or cancelled. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`conflict`: `amountMinor` is sent for an item with several lines (`reason: multiple_lines`); post it as scheduled, or change it in the app.\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/scheduled/{id}/cancel":{"post":{"operationId":"postScheduledByIdCancel","tags":["bills"],"summary":"Cancel a scheduled item","description":"Cancels an item that has not been posted, so it no longer shows as upcoming. Nothing is removed from the ledger and the item stays readable with status `cancelled`. Cancelling an item that is already cancelled changes nothing; a posted item cannot be cancelled.\n\nNeeds the `bills:delete` scope.","x-required-scope":"bills:delete","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string","minLength":1},"example":"sch_1"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The scheduled item id."},"name":{"type":"string","description":"What the item is called."},"notes":{"description":"Free-text notes.","type":["string","null"]},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction or cancelled."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"lines":{"type":"array","items":{"type":"object","properties":{"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the line moves money in or out of, or null."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The line category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"kind":{"type":"string","enum":["item","adjustment","surcharge"],"description":"`item` is something bought; `adjustment` a discount or correction; `surcharge` a fee or tip."},"itemName":{"description":"What is bought, when the line names it.","type":["string","null"]},"quantity":{"description":"How many are bought, when the line says.","type":["number","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["account","category","payee","kind","itemName","quantity","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The lines of the transaction it becomes."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or cancelling the item."},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","name","notes","direction","dueOn","status","account","counterAccount","category","payee","lines","remindDaysBefore","transactionId","postedAt","createdAt","version","amountMinor","amountDisplay"],"additionalProperties":false}}},"example":{"data":{"id":"sch_1","name":"Car service","notes":null,"direction":"expense","dueOn":"2026-11-14","status":"cancelled","amountMinor":18900,"amountDisplay":"£189.00","account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"lines":[{"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"category":{"id":"cat_2","name":"Car"},"payee":{"id":"pay_2","name":"Kwik Garage"},"kind":"item","itemName":null,"quantity":null,"amountMinor":-18900,"amountDisplay":"-£189.00"}],"remindDaysBefore":3,"transactionId":null,"postedAt":null,"createdAt":"2026-10-20T09:00:00.000Z","version":"1793000000000"}}}}},"400":{"description":"`validation_failed`: The item has already been posted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/recurring/{id}/pause":{"post":{"operationId":"postRecurringByIdPause","tags":["bills"],"summary":"Pause a recurring series","description":"Stops an active series from falling due until it is resumed. Nothing is removed and nothing is posted. Pausing a series that is already paused changes nothing.\n\nNeeds the `bills:write` scope.","x-required-scope":"bills:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string","minLength":1},"example":"ser_1"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The series id."},"name":{"type":"string","description":"What the series is called."},"status":{"type":"string","enum":["active","paused","ended","suggested","dismissed"],"description":"Whether it is running: `active`, `paused`, `ended`, or `suggested` / `dismissed` for ones spotted from your transactions."},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"cadence":{"type":"string","enum":["weekly","fortnightly","four_weekly","monthly","quarterly","yearly","custom"],"description":"How often it repeats."},"anchorDay":{"type":"integer","description":"Weekday (0 = Sunday) for weekly cadences, day of the month otherwise."},"anchorMonth":{"description":"Yearly series only.","type":["integer","null"]},"intervalDays":{"description":"Custom cadence only: every N days.","type":["integer","null"]},"nextDueOn":{"description":"The next day it falls due, YYYY-MM-DD; null when it has ended.","type":["string","null"]},"lastPostedOn":{"description":"The last day an occurrence was posted, YYYY-MM-DD, or null.","type":["string","null"]},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its default category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"notes":{"description":"Free-text notes.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing the series."},"expectedAmountMinor":{"type":"integer","description":"Expected amount, in whole pence."},"expectedAmountDisplay":{"type":"string","description":"Expected amount, ready to show, such as £12.50."},"upcomingOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Pending and pre-approved, soonest first."},"recentOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The last 12 posted, skipped or cancelled, newest first."}},"required":["id","name","status","direction","cadence","anchorDay","anchorMonth","intervalDays","nextDueOn","lastPostedOn","account","counterAccount","category","payee","remindDaysBefore","notes","version","expectedAmountMinor","expectedAmountDisplay","upcomingOccurrences","recentOccurrences"],"additionalProperties":false}}},"example":{"data":{"id":"ser_1","name":"Broadband","status":"paused","direction":"expense","cadence":"monthly","anchorDay":2,"anchorMonth":null,"intervalDays":null,"expectedAmountMinor":3299,"expectedAmountDisplay":"£32.99","nextDueOn":"2026-11-02","lastPostedOn":null,"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_1","name":"Bills"},"payee":{"id":"pay_1","name":"Fibre Co"},"remindDaysBefore":3,"notes":null,"version":"1793000000000","upcomingOccurrences":[{"id":"occ_1","dueOn":"2026-11-02","status":"pending","description":"Broadband","amountMinor":3299,"amountDisplay":"£32.99","transactionId":null,"postedAt":null}],"recentOccurrences":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`conflict`: Only an active series can be paused (`reason: series_not_active`).\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/recurring/{id}/resume":{"post":{"operationId":"postRecurringByIdResume","tags":["bills"],"summary":"Resume a recurring series","description":"Makes a paused (or ended) series active again. Open occurrences from before the pause that are now in the past are skipped, never posted; send `catchUpDueOns` to bring back some of the missed days as pending occurrences. Resuming a series that is already active changes nothing.\n\nNeeds the `bills:write` scope.","x-required-scope":"bills:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string","minLength":1},"example":"ser_1"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"default":{},"type":"object","properties":{"catchUpDueOns":{"description":"Missed due days to bring back as pending occurrences. They must fall in the missed window; none by default.","maxItems":36,"type":"array","items":{"type":"string"}}},"additionalProperties":false},"example":{}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The series id."},"name":{"type":"string","description":"What the series is called."},"status":{"type":"string","enum":["active","paused","ended","suggested","dismissed"],"description":"Whether it is running: `active`, `paused`, `ended`, or `suggested` / `dismissed` for ones spotted from your transactions."},"direction":{"type":"string","enum":["expense","income","transfer"],"description":"Whether money goes out, comes in or moves between your own accounts."},"cadence":{"type":"string","enum":["weekly","fortnightly","four_weekly","monthly","quarterly","yearly","custom"],"description":"How often it repeats."},"anchorDay":{"type":"integer","description":"Weekday (0 = Sunday) for weekly cadences, day of the month otherwise."},"anchorMonth":{"description":"Yearly series only.","type":["integer","null"]},"intervalDays":{"description":"Custom cadence only: every N days.","type":["integer","null"]},"nextDueOn":{"description":"The next day it falls due, YYYY-MM-DD; null when it has ended.","type":["string","null"]},"lastPostedOn":{"description":"The last day an occurrence was posted, YYYY-MM-DD, or null.","type":["string","null"]},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"The account the money leaves or arrives in, or null."},"counterAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The payment source id."},"name":{"type":"string","description":"The account, card or pot’s own name."},"path":{"type":"string","description":"The glance label the dashboard uses, such as `Lloyds · Main Card •••• 4242`."}},"required":["id","name","path"],"additionalProperties":false},{"type":"null"}],"description":"For a transfer, the account the money goes to."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Its default category, or null."},"payee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who is paid, or null."},"remindDaysBefore":{"type":"integer","description":"How many days before the due date to remind you."},"notes":{"description":"Free-text notes.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing the series."},"expectedAmountMinor":{"type":"integer","description":"Expected amount, in whole pence."},"expectedAmountDisplay":{"type":"string","description":"Expected amount, ready to show, such as £12.50."},"upcomingOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Pending and pre-approved, soonest first."},"recentOccurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The last 12 posted, skipped or cancelled, newest first."}},"required":["id","name","status","direction","cadence","anchorDay","anchorMonth","intervalDays","nextDueOn","lastPostedOn","account","counterAccount","category","payee","remindDaysBefore","notes","version","expectedAmountMinor","expectedAmountDisplay","upcomingOccurrences","recentOccurrences"],"additionalProperties":false}}},"example":{"data":{"id":"ser_1","name":"Broadband","status":"active","direction":"expense","cadence":"monthly","anchorDay":2,"anchorMonth":null,"intervalDays":null,"expectedAmountMinor":3299,"expectedAmountDisplay":"£32.99","nextDueOn":"2026-11-02","lastPostedOn":null,"account":{"id":"src_1","name":"Everyday account","path":"Example Bank · Everyday account"},"counterAccount":null,"category":{"id":"cat_1","name":"Bills"},"payee":{"id":"pay_1","name":"Fibre Co"},"remindDaysBefore":3,"notes":null,"version":"1793000000000","upcomingOccurrences":[{"id":"occ_1","dueOn":"2026-11-02","status":"pending","description":"Broadband","amountMinor":3299,"amountDisplay":"£32.99","transactionId":null,"postedAt":null}],"recentOccurrences":[]}}}}},"400":{"description":"`validation_failed`: A day in `catchUpDueOns` is not a `YYYY-MM-DD` day. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`conflict`: Only a paused or ended series can be resumed (`reason: series_not_paused`).\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/recurring/{id}/occurrences/{dueOn}/post":{"post":{"operationId":"postRecurringByIdOccurrencesByDueOnPost","tags":["bills"],"summary":"Post a recurring occurrence to the ledger","description":"Posts the occurrence due on that day as a real transaction (the series’ category and payee are needed) and links it to the series. The answer is the occurrence, now `posted`, with the new `transactionId`. Send `amountMinor` or `date` to post a different amount or date than planned (the amount only on a plain, single-line occurrence). An occurrence not yet due (its due day is after today, UK time) cannot be posted, whatever `date` says: pre-approve it in the app or wait; one already posted or skipped cannot be posted either. On its due day it can be posted before its posting time, pending or pre-approved: without a `date`, the transaction is then dated the moment you post it, never later that day.\n\nNeeds the `bills:write` scope.","x-required-scope":"bills:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The recurring series id.","schema":{"type":"string","minLength":1},"example":"ser_1"},{"name":"dueOn","in":"path","required":true,"description":"The occurrence’s due day, `YYYY-MM-DD`, as `dueOn` in the series’ occurrences.","schema":{"type":"string"},"example":"2026-11-02"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"description":"The transaction date to post it under (default: its due day). `YYYY-MM-DD`.","type":"string"},"amountMinor":{"description":"Post a different amount (in pence, positive) than planned.","type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"additionalProperties":false},"example":{"amountMinor":3299}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."},"seriesId":{"type":"string","description":"The series it belongs to."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay","seriesId"],"additionalProperties":false}}},"example":{"data":{"id":"occ_1","seriesId":"ser_1","dueOn":"2026-11-02","status":"posted","description":"Broadband","amountMinor":3299,"amountDisplay":"£32.99","transactionId":"txn_1","postedAt":"2026-11-02T08:00:00.000Z"}}}}},"400":{"description":"`validation_failed`: The occurrence is not due yet (`reason: not_due_yet`), or is already posted or skipped. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `bills:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: The series has no occurrence due on that day. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: `amountMinor` is sent for an occurrence with several lines (`reason: multiple_lines`).\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/recurring/{id}/occurrences/{dueOn}/skip":{"post":{"operationId":"postRecurringByIdOccurrencesByDueOnSkip","tags":["bills"],"summary":"Skip a recurring occurrence","description":"Marks the occurrence due on that day as skipped: it will not be posted and stops showing as upcoming, and the series carries on. Nothing is posted to the ledger. Only a pending or pre-approved occurrence can be skipped.\n\nNeeds the `bills:write` scope.","x-required-scope":"bills:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The recurring series id.","schema":{"type":"string","minLength":1},"example":"ser_1"},{"name":"dueOn","in":"path","required":true,"description":"The occurrence’s due day, `YYYY-MM-DD`, as `dueOn` in the series’ occurrences.","schema":{"type":"string"},"example":"2026-11-02"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The occurrence id."},"dueOn":{"type":"string","description":"The day it is due, YYYY-MM-DD."},"status":{"type":"string","enum":["pending","pre_approved","posted","skipped","cancelled"],"description":"Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled."},"description":{"type":"string","description":"What the transaction will be called."},"transactionId":{"description":"The ledger transaction it was posted as. Always null unless the key can read transactions.","type":["string","null"]},"postedAt":{"description":"When it was posted, ISO 8601 in UTC; null until then.","type":["string","null"]},"amountMinor":{"type":"integer","description":"Amount, in whole pence."},"amountDisplay":{"type":"string","description":"Amount, ready to show, such as £12.50."},"seriesId":{"type":"string","description":"The series it belongs to."}},"required":["id","dueOn","status","description","transactionId","postedAt","amountMinor","amountDisplay","seriesId"],"additionalProperties":false}}},"example":{"data":{"id":"occ_1","seriesId":"ser_1","dueOn":"2026-11-02","status":"skipped","description":"Broadband","amountMinor":3299,"amountDisplay":"£32.99","transactionId":null,"postedAt":null}}}}},"400":{"description":"`validation_failed`: Only a pending or pre-approved occurrence can be skipped.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden`: The key is limited to some accounts and this would involve another one (`reason: account_limit`).\n\n`forbidden_scope`: The key lacks the `bills:write` scope; `requiredScope` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: The series has no occurrence due on that day. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/budgets":{"get":{"operationId":"getBudgets","tags":["budgets"],"summary":"List budgets for a month","description":"Every budget with its figures for one month, the same numbers as the Budgets page. `planned` is the month's allocation, `funding` envelope top-ups and transfers, `spent` what the ledger counted against the budget, and `remaining` what is left (negative when over; for rollover budgets it includes the `opening` balance carried in). `progressPercent` is spent as a share of everything available before it was spent, as on the Budgets page. `status` is `over` when nothing is left, `near` once the budget's own alert threshold has been reached, otherwise `under`. Archived budgets are hidden unless `archived=include|only`. The `meta` block says whether budgets are switched on for the account and gives the month's uncategorised spending and the cash reserved by active envelopes. To keep a copy in step, send `updatedSince`: only budgets edited since then come back, archived ones included and flagged. A budget counts as edited when the budget itself changes; its monthly figures move with your transactions without that, so re-read the months you show.\n\nNeeds the `budgets:read` scope.","x-required-scope":"budgets:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"month","in":"query","required":false,"description":"The month to show, `YYYY-MM`. Defaults to the current UK month.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"example":"2026-10"},{"name":"archived","in":"query","required":false,"description":"Archived items: `exclude` (default), `include` or `only`. With `updatedSince` the default is `include`, so a change to archived shows.","schema":{"type":"string","enum":["exclude","include","only"]}},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The budget id."},"name":{"type":"string","description":"The budget name."},"scope":{"type":"string","enum":["category","account","envelope"],"description":"What it watches: a `category`, an `account` or an `envelope` of money set aside."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category (and its subcategories) this budget watches."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The financial account this budget is limited to."},"month":{"type":"string","description":"The month these figures are for, YYYY-MM."},"rolloverMode":{"type":"string","enum":["none","carry","buffer"],"description":"What happens to the unspent amount at month end: nothing, carry it forward, or hold it in a buffer."},"alertThresholdPercent":{"description":"Warn at this percentage of the budget used; null for no alert.","type":["integer","null"]},"archived":{"type":"boolean","description":"True once the budget has been archived."},"version":{"type":"string","description":"Send as `If-Match` when editing the budget."},"progressPercent":{"type":"integer","description":"Spent as a percentage of what was available to spend this month."},"status":{"type":"string","enum":["under","near","over"],"description":"`under` while there is room, `near` once the alert threshold is reached, `over` once everything available is spent."},"plannedMinor":{"type":"integer","description":"Amount planned for the month, in whole pence."},"plannedDisplay":{"type":"string","description":"Amount planned for the month, ready to show, such as £12.50."},"openingMinor":{"type":"integer","description":"Amount carried in from earlier months, in whole pence."},"openingDisplay":{"type":"string","description":"Amount carried in from earlier months, ready to show, such as £12.50."},"fundingMinor":{"type":"integer","description":"Amount added to the budget this month, in whole pence."},"fundingDisplay":{"type":"string","description":"Amount added to the budget this month, ready to show, such as £12.50."},"bufferDrawMinor":{"type":"integer","description":"Amount taken from the buffer to cover overspending, in whole pence."},"bufferDrawDisplay":{"type":"string","description":"Amount taken from the buffer to cover overspending, ready to show, such as £12.50."},"spentMinor":{"type":"integer","description":"Amount spent this month, in whole pence."},"spentDisplay":{"type":"string","description":"Amount spent this month, ready to show, such as £12.50."},"remainingMinor":{"type":"integer","description":"Amount left to spend; negative when over, in whole pence."},"remainingDisplay":{"type":"string","description":"Amount left to spend; negative when over, ready to show, such as £12.50."},"overLimitMinor":{"type":"integer","description":"Amount spent beyond what was available, in whole pence."},"overLimitDisplay":{"type":"string","description":"Amount spent beyond what was available, ready to show, such as £12.50."},"bufferMinor":{"type":"integer","description":"Amount held in the buffer, in whole pence."},"bufferDisplay":{"type":"string","description":"Amount held in the buffer, ready to show, such as £12.50."},"bufferShortfallMinor":{"type":"integer","description":"Amount the buffer is short of what it should hold, in whole pence."},"bufferShortfallDisplay":{"type":"string","description":"Amount the buffer is short of what it should hold, ready to show, such as £12.50."}},"required":["id","name","scope","category","account","month","rolloverMode","alertThresholdPercent","archived","version","progressPercent","status","plannedMinor","plannedDisplay","openingMinor","openingDisplay","fundingMinor","fundingDisplay","bufferDrawMinor","bufferDrawDisplay","spentMinor","spentDisplay","remainingMinor","remainingDisplay","overLimitMinor","overLimitDisplay","bufferMinor","bufferDisplay","bufferShortfallMinor","bufferShortfallDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"bud_groceries","name":"Groceries","scope":"category","category":{"id":"cat_groceries","name":"Groceries"},"account":null,"month":"2026-10","plannedMinor":40000,"plannedDisplay":"£400.00","openingMinor":0,"openingDisplay":"£0.00","fundingMinor":0,"fundingDisplay":"£0.00","bufferDrawMinor":0,"bufferDrawDisplay":"£0.00","spentMinor":31250,"spentDisplay":"£312.50","remainingMinor":8750,"remainingDisplay":"£87.50","overLimitMinor":0,"overLimitDisplay":"£0.00","bufferMinor":0,"bufferDisplay":"£0.00","bufferShortfallMinor":0,"bufferShortfallDisplay":"£0.00","progressPercent":78,"status":"near","rolloverMode":"none","alertThresholdPercent":75,"archived":false,"version":"1792000000000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postBudgets","tags":["budgets"],"summary":"Create a budget","description":"Creates a budget, optionally with its first month's allocation (`plannedMinor`, in pence, for `month`). A `category` budget needs `categoryId` and an `account` budget needs `accountId`. Budgets must be switched on in the app first, otherwise the answer is 400. The answer is the budget as `GET /budgets/{id}` shows it for `month`.\n\nNeeds the `budgets:write` scope.","x-required-scope":"budgets:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":160,"description":"The budget name."},"scope":{"type":"string","enum":["category","account","envelope"],"description":"`category` watches one category and its subcategories, `account` one financial account, `envelope` is money you put aside and draw on."},"categoryId":{"description":"Required for a `category` budget.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"accountId":{"description":"The financial account, required for an `account` budget.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"rolloverMode":{"description":"Defaults to `none`.","type":"string","enum":["none","carry","buffer"]},"alertThresholdPercent":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}],"description":"Percentage of the budget at which to warn you, 1–100. Null for no warning."},"month":{"description":"The month the first allocation is for, `YYYY-MM`. Defaults to the current UK month.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"plannedMinor":{"description":"The first month's allocation in pence. Leave out to set it later with `PUT /budgets/{id}/months/{month}`.","type":"integer","minimum":0,"maximum":2147483647}},"required":["name","scope"],"additionalProperties":false},"example":{"name":"Groceries","scope":"category","categoryId":"cat_groceries","rolloverMode":"none","alertThresholdPercent":75,"month":"2026-10","plannedMinor":40000}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The budget id."},"name":{"type":"string","description":"The budget name."},"scope":{"type":"string","enum":["category","account","envelope"],"description":"What it watches: a `category`, an `account` or an `envelope` of money set aside."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category (and its subcategories) this budget watches."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The financial account this budget is limited to."},"month":{"type":"string","description":"The month these figures are for, YYYY-MM."},"rolloverMode":{"type":"string","enum":["none","carry","buffer"],"description":"What happens to the unspent amount at month end: nothing, carry it forward, or hold it in a buffer."},"alertThresholdPercent":{"description":"Warn at this percentage of the budget used; null for no alert.","type":["integer","null"]},"archived":{"type":"boolean","description":"True once the budget has been archived."},"version":{"type":"string","description":"Send as `If-Match` when editing the budget."},"progressPercent":{"type":"integer","description":"Spent as a percentage of what was available to spend this month."},"status":{"type":"string","enum":["under","near","over"],"description":"`under` while there is room, `near` once the alert threshold is reached, `over` once everything available is spent."},"plannedMinor":{"type":"integer","description":"Amount planned for the month, in whole pence."},"plannedDisplay":{"type":"string","description":"Amount planned for the month, ready to show, such as £12.50."},"openingMinor":{"type":"integer","description":"Amount carried in from earlier months, in whole pence."},"openingDisplay":{"type":"string","description":"Amount carried in from earlier months, ready to show, such as £12.50."},"fundingMinor":{"type":"integer","description":"Amount added to the budget this month, in whole pence."},"fundingDisplay":{"type":"string","description":"Amount added to the budget this month, ready to show, such as £12.50."},"bufferDrawMinor":{"type":"integer","description":"Amount taken from the buffer to cover overspending, in whole pence."},"bufferDrawDisplay":{"type":"string","description":"Amount taken from the buffer to cover overspending, ready to show, such as £12.50."},"spentMinor":{"type":"integer","description":"Amount spent this month, in whole pence."},"spentDisplay":{"type":"string","description":"Amount spent this month, ready to show, such as £12.50."},"remainingMinor":{"type":"integer","description":"Amount left to spend; negative when over, in whole pence."},"remainingDisplay":{"type":"string","description":"Amount left to spend; negative when over, ready to show, such as £12.50."},"overLimitMinor":{"type":"integer","description":"Amount spent beyond what was available, in whole pence."},"overLimitDisplay":{"type":"string","description":"Amount spent beyond what was available, ready to show, such as £12.50."},"bufferMinor":{"type":"integer","description":"Amount held in the buffer, in whole pence."},"bufferDisplay":{"type":"string","description":"Amount held in the buffer, ready to show, such as £12.50."},"bufferShortfallMinor":{"type":"integer","description":"Amount the buffer is short of what it should hold, in whole pence."},"bufferShortfallDisplay":{"type":"string","description":"Amount the buffer is short of what it should hold, ready to show, such as £12.50."},"history":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"The month these figures are for, YYYY-MM."},"progressPercent":{"type":"integer","description":"Spent as a percentage of what was available to spend this month."},"status":{"type":"string","enum":["under","near","over"],"description":"`under` while there is room, `near` once the alert threshold is reached, `over` once everything available is spent."},"plannedMinor":{"type":"integer","description":"Amount planned for the month, in whole pence."},"plannedDisplay":{"type":"string","description":"Amount planned for the month, ready to show, such as £12.50."},"openingMinor":{"type":"integer","description":"Amount carried in from earlier months, in whole pence."},"openingDisplay":{"type":"string","description":"Amount carried in from earlier months, ready to show, such as £12.50."},"fundingMinor":{"type":"integer","description":"Amount added to the budget this month, in whole pence."},"fundingDisplay":{"type":"string","description":"Amount added to the budget this month, ready to show, such as £12.50."},"bufferDrawMinor":{"type":"integer","description":"Amount taken from the buffer to cover overspending, in whole pence."},"bufferDrawDisplay":{"type":"string","description":"Amount taken from the buffer to cover overspending, ready to show, such as £12.50."},"spentMinor":{"type":"integer","description":"Amount spent this month, in whole pence."},"spentDisplay":{"type":"string","description":"Amount spent this month, ready to show, such as £12.50."},"remainingMinor":{"type":"integer","description":"Amount left to spend; negative when over, in whole pence."},"remainingDisplay":{"type":"string","description":"Amount left to spend; negative when over, ready to show, such as £12.50."},"overLimitMinor":{"type":"integer","description":"Amount spent beyond what was available, in whole pence."},"overLimitDisplay":{"type":"string","description":"Amount spent beyond what was available, ready to show, such as £12.50."},"bufferMinor":{"type":"integer","description":"Amount held in the buffer, in whole pence."},"bufferDisplay":{"type":"string","description":"Amount held in the buffer, ready to show, such as £12.50."},"bufferShortfallMinor":{"type":"integer","description":"Amount the buffer is short of what it should hold, in whole pence."},"bufferShortfallDisplay":{"type":"string","description":"Amount the buffer is short of what it should hold, ready to show, such as £12.50."}},"required":["month","progressPercent","status","plannedMinor","plannedDisplay","openingMinor","openingDisplay","fundingMinor","fundingDisplay","bufferDrawMinor","bufferDrawDisplay","spentMinor","spentDisplay","remainingMinor","remainingDisplay","overLimitMinor","overLimitDisplay","bufferMinor","bufferDisplay","bufferShortfallMinor","bufferShortfallDisplay"],"additionalProperties":false},"description":"The earlier months, with the same figures for each."}},"required":["id","name","scope","category","account","month","rolloverMode","alertThresholdPercent","archived","version","progressPercent","status","plannedMinor","plannedDisplay","openingMinor","openingDisplay","fundingMinor","fundingDisplay","bufferDrawMinor","bufferDrawDisplay","spentMinor","spentDisplay","remainingMinor","remainingDisplay","overLimitMinor","overLimitDisplay","bufferMinor","bufferDisplay","bufferShortfallMinor","bufferShortfallDisplay","history"],"additionalProperties":false}}},"example":{"data":{"id":"bud_groceries","name":"Groceries","scope":"category","category":{"id":"cat_groceries","name":"Groceries"},"account":null,"month":"2026-10","plannedMinor":40000,"plannedDisplay":"£400.00","openingMinor":0,"openingDisplay":"£0.00","fundingMinor":0,"fundingDisplay":"£0.00","bufferDrawMinor":0,"bufferDrawDisplay":"£0.00","spentMinor":31250,"spentDisplay":"£312.50","remainingMinor":8750,"remainingDisplay":"£87.50","overLimitMinor":0,"overLimitDisplay":"£0.00","bufferMinor":0,"bufferDisplay":"£0.00","bufferShortfallMinor":0,"bufferShortfallDisplay":"£0.00","progressPercent":78,"status":"near","rolloverMode":"none","alertThresholdPercent":75,"archived":false,"version":"1792000000000","history":[]}}}}},"400":{"description":"`validation_failed`: Budgets are not switched on, a `category` budget has no `categoryId`, or an `account` budget has no `accountId`. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The category or account does not exist or belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/budgets/{id}":{"get":{"operationId":"getBudgetsById","tags":["budgets"],"summary":"Get a budget","description":"One budget for a month, with `history`: its figures for each of the last 12 months up to that month, newest first. `planned` is the month's allocation, `funding` envelope top-ups and transfers, `spent` what the ledger counted against the budget, and `remaining` what is left (negative when over; for rollover budgets it includes the `opening` balance carried in). `progressPercent` is spent as a share of everything available before it was spent, as on the Budgets page. `status` is `over` when nothing is left, `near` once the budget's own alert threshold has been reached, otherwise `under`. A budget that had not started by the requested month answers 404.\n\nNeeds the `budgets:read` scope.","x-required-scope":"budgets:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The budget id.","schema":{"type":"string","minLength":1},"example":"bud_groceries"},{"name":"month","in":"query","required":false,"description":"The month to show, `YYYY-MM`. Defaults to the current UK month.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"example":"2026-10"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The budget id."},"name":{"type":"string","description":"The budget name."},"scope":{"type":"string","enum":["category","account","envelope"],"description":"What it watches: a `category`, an `account` or an `envelope` of money set aside."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category (and its subcategories) this budget watches."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The financial account this budget is limited to."},"month":{"type":"string","description":"The month these figures are for, YYYY-MM."},"rolloverMode":{"type":"string","enum":["none","carry","buffer"],"description":"What happens to the unspent amount at month end: nothing, carry it forward, or hold it in a buffer."},"alertThresholdPercent":{"description":"Warn at this percentage of the budget used; null for no alert.","type":["integer","null"]},"archived":{"type":"boolean","description":"True once the budget has been archived."},"version":{"type":"string","description":"Send as `If-Match` when editing the budget."},"progressPercent":{"type":"integer","description":"Spent as a percentage of what was available to spend this month."},"status":{"type":"string","enum":["under","near","over"],"description":"`under` while there is room, `near` once the alert threshold is reached, `over` once everything available is spent."},"plannedMinor":{"type":"integer","description":"Amount planned for the month, in whole pence."},"plannedDisplay":{"type":"string","description":"Amount planned for the month, ready to show, such as £12.50."},"openingMinor":{"type":"integer","description":"Amount carried in from earlier months, in whole pence."},"openingDisplay":{"type":"string","description":"Amount carried in from earlier months, ready to show, such as £12.50."},"fundingMinor":{"type":"integer","description":"Amount added to the budget this month, in whole pence."},"fundingDisplay":{"type":"string","description":"Amount added to the budget this month, ready to show, such as £12.50."},"bufferDrawMinor":{"type":"integer","description":"Amount taken from the buffer to cover overspending, in whole pence."},"bufferDrawDisplay":{"type":"string","description":"Amount taken from the buffer to cover overspending, ready to show, such as £12.50."},"spentMinor":{"type":"integer","description":"Amount spent this month, in whole pence."},"spentDisplay":{"type":"string","description":"Amount spent this month, ready to show, such as £12.50."},"remainingMinor":{"type":"integer","description":"Amount left to spend; negative when over, in whole pence."},"remainingDisplay":{"type":"string","description":"Amount left to spend; negative when over, ready to show, such as £12.50."},"overLimitMinor":{"type":"integer","description":"Amount spent beyond what was available, in whole pence."},"overLimitDisplay":{"type":"string","description":"Amount spent beyond what was available, ready to show, such as £12.50."},"bufferMinor":{"type":"integer","description":"Amount held in the buffer, in whole pence."},"bufferDisplay":{"type":"string","description":"Amount held in the buffer, ready to show, such as £12.50."},"bufferShortfallMinor":{"type":"integer","description":"Amount the buffer is short of what it should hold, in whole pence."},"bufferShortfallDisplay":{"type":"string","description":"Amount the buffer is short of what it should hold, ready to show, such as £12.50."},"history":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"The month these figures are for, YYYY-MM."},"progressPercent":{"type":"integer","description":"Spent as a percentage of what was available to spend this month."},"status":{"type":"string","enum":["under","near","over"],"description":"`under` while there is room, `near` once the alert threshold is reached, `over` once everything available is spent."},"plannedMinor":{"type":"integer","description":"Amount planned for the month, in whole pence."},"plannedDisplay":{"type":"string","description":"Amount planned for the month, ready to show, such as £12.50."},"openingMinor":{"type":"integer","description":"Amount carried in from earlier months, in whole pence."},"openingDisplay":{"type":"string","description":"Amount carried in from earlier months, ready to show, such as £12.50."},"fundingMinor":{"type":"integer","description":"Amount added to the budget this month, in whole pence."},"fundingDisplay":{"type":"string","description":"Amount added to the budget this month, ready to show, such as £12.50."},"bufferDrawMinor":{"type":"integer","description":"Amount taken from the buffer to cover overspending, in whole pence."},"bufferDrawDisplay":{"type":"string","description":"Amount taken from the buffer to cover overspending, ready to show, such as £12.50."},"spentMinor":{"type":"integer","description":"Amount spent this month, in whole pence."},"spentDisplay":{"type":"string","description":"Amount spent this month, ready to show, such as £12.50."},"remainingMinor":{"type":"integer","description":"Amount left to spend; negative when over, in whole pence."},"remainingDisplay":{"type":"string","description":"Amount left to spend; negative when over, ready to show, such as £12.50."},"overLimitMinor":{"type":"integer","description":"Amount spent beyond what was available, in whole pence."},"overLimitDisplay":{"type":"string","description":"Amount spent beyond what was available, ready to show, such as £12.50."},"bufferMinor":{"type":"integer","description":"Amount held in the buffer, in whole pence."},"bufferDisplay":{"type":"string","description":"Amount held in the buffer, ready to show, such as £12.50."},"bufferShortfallMinor":{"type":"integer","description":"Amount the buffer is short of what it should hold, in whole pence."},"bufferShortfallDisplay":{"type":"string","description":"Amount the buffer is short of what it should hold, ready to show, such as £12.50."}},"required":["month","progressPercent","status","plannedMinor","plannedDisplay","openingMinor","openingDisplay","fundingMinor","fundingDisplay","bufferDrawMinor","bufferDrawDisplay","spentMinor","spentDisplay","remainingMinor","remainingDisplay","overLimitMinor","overLimitDisplay","bufferMinor","bufferDisplay","bufferShortfallMinor","bufferShortfallDisplay"],"additionalProperties":false},"description":"The earlier months, with the same figures for each."}},"required":["id","name","scope","category","account","month","rolloverMode","alertThresholdPercent","archived","version","progressPercent","status","plannedMinor","plannedDisplay","openingMinor","openingDisplay","fundingMinor","fundingDisplay","bufferDrawMinor","bufferDrawDisplay","spentMinor","spentDisplay","remainingMinor","remainingDisplay","overLimitMinor","overLimitDisplay","bufferMinor","bufferDisplay","bufferShortfallMinor","bufferShortfallDisplay","history"],"additionalProperties":false}}},"example":{"data":{"id":"bud_groceries","name":"Groceries","scope":"category","category":{"id":"cat_groceries","name":"Groceries"},"account":null,"month":"2026-10","plannedMinor":40000,"plannedDisplay":"£400.00","openingMinor":0,"openingDisplay":"£0.00","fundingMinor":0,"fundingDisplay":"£0.00","bufferDrawMinor":0,"bufferDrawDisplay":"£0.00","spentMinor":31250,"spentDisplay":"£312.50","remainingMinor":8750,"remainingDisplay":"£87.50","overLimitMinor":0,"overLimitDisplay":"£0.00","bufferMinor":0,"bufferDisplay":"£0.00","bufferShortfallMinor":0,"bufferShortfallDisplay":"£0.00","progressPercent":78,"status":"near","rolloverMode":"none","alertThresholdPercent":75,"archived":false,"version":"1792000000000","history":[{"month":"2026-10","plannedMinor":40000,"plannedDisplay":"£400.00","openingMinor":0,"openingDisplay":"£0.00","fundingMinor":0,"fundingDisplay":"£0.00","bufferDrawMinor":0,"bufferDrawDisplay":"£0.00","spentMinor":31250,"spentDisplay":"£312.50","remainingMinor":8750,"remainingDisplay":"£87.50","overLimitMinor":0,"overLimitDisplay":"£0.00","bufferMinor":0,"bufferDisplay":"£0.00","bufferShortfallMinor":0,"bufferShortfallDisplay":"£0.00","progressPercent":78,"status":"near"},{"month":"2026-09","plannedMinor":40000,"plannedDisplay":"£400.00","openingMinor":0,"openingDisplay":"£0.00","fundingMinor":0,"fundingDisplay":"£0.00","bufferDrawMinor":0,"bufferDrawDisplay":"£0.00","spentMinor":38100,"spentDisplay":"£381.00","remainingMinor":1900,"remainingDisplay":"£19.00","overLimitMinor":0,"overLimitDisplay":"£0.00","bufferMinor":0,"bufferDisplay":"£0.00","bufferShortfallMinor":0,"bufferShortfallDisplay":"£0.00","progressPercent":95,"status":"near"}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The budget had not started by the requested `month`. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"patchBudgetsById","tags":["budgets"],"summary":"Edit or archive a budget","description":"Changes the fields you send and leaves the rest. The budget's type (`scope`) cannot change, and its rollover mode cannot change once it has buffer draws. `archived: true` archives it; an archived budget cannot be restored or edited at all (409 `budget_archived`). Monthly allocations are set with `PUT /budgets/{id}/months/{month}`. Send the `version` you last read as `If-Match` (or in the body): if the budget has changed since, the answer is 412 `version_conflict`. Edits are applied first, then the archive; if the archive is refused, the edits stay. The answer is the budget as `GET /budgets/{id}` shows it for `month`.\n\nNeeds the `budgets:write` scope.","x-required-scope":"budgets:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The budget id.","schema":{"type":"string","minLength":1},"example":"bud_groceries"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"A new name.","type":"string","minLength":1,"maxLength":160},"categoryId":{"description":"Watch a different category (category budgets).","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"accountId":{"description":"Watch a different financial account (account budgets).","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"rolloverMode":{"type":"string","enum":["none","carry","buffer"],"description":"What happens to money left over: `none` (it resets), `carry` (it rolls into next month) or `buffer` (it builds a buffer)."},"alertThresholdPercent":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}],"description":"Percentage of the budget at which to warn you, 1–100. Null for no warning."},"archived":{"description":"True archives the budget. A budget cannot be restored once archived: `false` on an archived budget answers 409.","type":"boolean"},"month":{"description":"The month to show in the answer, `YYYY-MM`. Defaults to the current UK month.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"version":{"description":"The `version` you last read, as an alternative to the `If-Match` header.","type":"string"}},"additionalProperties":false},"example":{"name":"Food shopping","alertThresholdPercent":80}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The budget id."},"name":{"type":"string","description":"The budget name."},"scope":{"type":"string","enum":["category","account","envelope"],"description":"What it watches: a `category`, an `account` or an `envelope` of money set aside."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category (and its subcategories) this budget watches."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The financial account this budget is limited to."},"month":{"type":"string","description":"The month these figures are for, YYYY-MM."},"rolloverMode":{"type":"string","enum":["none","carry","buffer"],"description":"What happens to the unspent amount at month end: nothing, carry it forward, or hold it in a buffer."},"alertThresholdPercent":{"description":"Warn at this percentage of the budget used; null for no alert.","type":["integer","null"]},"archived":{"type":"boolean","description":"True once the budget has been archived."},"version":{"type":"string","description":"Send as `If-Match` when editing the budget."},"progressPercent":{"type":"integer","description":"Spent as a percentage of what was available to spend this month."},"status":{"type":"string","enum":["under","near","over"],"description":"`under` while there is room, `near` once the alert threshold is reached, `over` once everything available is spent."},"plannedMinor":{"type":"integer","description":"Amount planned for the month, in whole pence."},"plannedDisplay":{"type":"string","description":"Amount planned for the month, ready to show, such as £12.50."},"openingMinor":{"type":"integer","description":"Amount carried in from earlier months, in whole pence."},"openingDisplay":{"type":"string","description":"Amount carried in from earlier months, ready to show, such as £12.50."},"fundingMinor":{"type":"integer","description":"Amount added to the budget this month, in whole pence."},"fundingDisplay":{"type":"string","description":"Amount added to the budget this month, ready to show, such as £12.50."},"bufferDrawMinor":{"type":"integer","description":"Amount taken from the buffer to cover overspending, in whole pence."},"bufferDrawDisplay":{"type":"string","description":"Amount taken from the buffer to cover overspending, ready to show, such as £12.50."},"spentMinor":{"type":"integer","description":"Amount spent this month, in whole pence."},"spentDisplay":{"type":"string","description":"Amount spent this month, ready to show, such as £12.50."},"remainingMinor":{"type":"integer","description":"Amount left to spend; negative when over, in whole pence."},"remainingDisplay":{"type":"string","description":"Amount left to spend; negative when over, ready to show, such as £12.50."},"overLimitMinor":{"type":"integer","description":"Amount spent beyond what was available, in whole pence."},"overLimitDisplay":{"type":"string","description":"Amount spent beyond what was available, ready to show, such as £12.50."},"bufferMinor":{"type":"integer","description":"Amount held in the buffer, in whole pence."},"bufferDisplay":{"type":"string","description":"Amount held in the buffer, ready to show, such as £12.50."},"bufferShortfallMinor":{"type":"integer","description":"Amount the buffer is short of what it should hold, in whole pence."},"bufferShortfallDisplay":{"type":"string","description":"Amount the buffer is short of what it should hold, ready to show, such as £12.50."},"history":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"The month these figures are for, YYYY-MM."},"progressPercent":{"type":"integer","description":"Spent as a percentage of what was available to spend this month."},"status":{"type":"string","enum":["under","near","over"],"description":"`under` while there is room, `near` once the alert threshold is reached, `over` once everything available is spent."},"plannedMinor":{"type":"integer","description":"Amount planned for the month, in whole pence."},"plannedDisplay":{"type":"string","description":"Amount planned for the month, ready to show, such as £12.50."},"openingMinor":{"type":"integer","description":"Amount carried in from earlier months, in whole pence."},"openingDisplay":{"type":"string","description":"Amount carried in from earlier months, ready to show, such as £12.50."},"fundingMinor":{"type":"integer","description":"Amount added to the budget this month, in whole pence."},"fundingDisplay":{"type":"string","description":"Amount added to the budget this month, ready to show, such as £12.50."},"bufferDrawMinor":{"type":"integer","description":"Amount taken from the buffer to cover overspending, in whole pence."},"bufferDrawDisplay":{"type":"string","description":"Amount taken from the buffer to cover overspending, ready to show, such as £12.50."},"spentMinor":{"type":"integer","description":"Amount spent this month, in whole pence."},"spentDisplay":{"type":"string","description":"Amount spent this month, ready to show, such as £12.50."},"remainingMinor":{"type":"integer","description":"Amount left to spend; negative when over, in whole pence."},"remainingDisplay":{"type":"string","description":"Amount left to spend; negative when over, ready to show, such as £12.50."},"overLimitMinor":{"type":"integer","description":"Amount spent beyond what was available, in whole pence."},"overLimitDisplay":{"type":"string","description":"Amount spent beyond what was available, ready to show, such as £12.50."},"bufferMinor":{"type":"integer","description":"Amount held in the buffer, in whole pence."},"bufferDisplay":{"type":"string","description":"Amount held in the buffer, ready to show, such as £12.50."},"bufferShortfallMinor":{"type":"integer","description":"Amount the buffer is short of what it should hold, in whole pence."},"bufferShortfallDisplay":{"type":"string","description":"Amount the buffer is short of what it should hold, ready to show, such as £12.50."}},"required":["month","progressPercent","status","plannedMinor","plannedDisplay","openingMinor","openingDisplay","fundingMinor","fundingDisplay","bufferDrawMinor","bufferDrawDisplay","spentMinor","spentDisplay","remainingMinor","remainingDisplay","overLimitMinor","overLimitDisplay","bufferMinor","bufferDisplay","bufferShortfallMinor","bufferShortfallDisplay"],"additionalProperties":false},"description":"The earlier months, with the same figures for each."}},"required":["id","name","scope","category","account","month","rolloverMode","alertThresholdPercent","archived","version","progressPercent","status","plannedMinor","plannedDisplay","openingMinor","openingDisplay","fundingMinor","fundingDisplay","bufferDrawMinor","bufferDrawDisplay","spentMinor","spentDisplay","remainingMinor","remainingDisplay","overLimitMinor","overLimitDisplay","bufferMinor","bufferDisplay","bufferShortfallMinor","bufferShortfallDisplay","history"],"additionalProperties":false}}},"example":{"data":{"id":"bud_groceries","name":"Food shopping","scope":"category","category":{"id":"cat_groceries","name":"Groceries"},"account":null,"month":"2026-10","plannedMinor":40000,"plannedDisplay":"£400.00","openingMinor":0,"openingDisplay":"£0.00","fundingMinor":0,"fundingDisplay":"£0.00","bufferDrawMinor":0,"bufferDrawDisplay":"£0.00","spentMinor":31250,"spentDisplay":"£312.50","remainingMinor":8750,"remainingDisplay":"£87.50","overLimitMinor":0,"overLimitDisplay":"£0.00","bufferMinor":0,"bufferDisplay":"£0.00","bufferShortfallMinor":0,"bufferShortfallDisplay":"£0.00","progressPercent":78,"status":"near","rolloverMode":"none","alertThresholdPercent":80,"archived":false,"version":"1792000000000","history":[]}}}}},"400":{"description":"`validation_failed`: The body is empty, the `scope` is changed, or the rollover mode changes once the budget has buffer draws. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`conflict`: The budget is archived, so it cannot be edited or restored (`reason: budget_archived`).\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/budgets/{id}/months/{month}":{"put":{"operationId":"putBudgetsByIdMonthsByMonth","tags":["budgets"],"summary":"Set a budget's allocation for a month","description":"Sets what is allocated to the budget in one month, in pence; sending the same amount again changes nothing. A month the budget has no allocation for yet is created. An archived budget answers 409 `budget_archived`. Setting a month does not change the budget's own `version`, so `If-Match` here only guards against the budget itself having been edited or archived since you read it. The answer is the budget as `GET /budgets/{id}?month=…` shows it.\n\nNeeds the `budgets:write` scope.","x-required-scope":"budgets:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The budget id.","schema":{"type":"string","minLength":1},"example":"bud_groceries"},{"name":"month","in":"path","required":true,"description":"The month, `YYYY-MM`.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"example":"2026-11"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":0,"maximum":2147483647,"description":"The month's allocation in pence."},"version":{"description":"The budget `version` you last read, as an alternative to the `If-Match` header.","type":"string"}},"required":["amountMinor"],"additionalProperties":false},"example":{"amountMinor":42500}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The budget id."},"name":{"type":"string","description":"The budget name."},"scope":{"type":"string","enum":["category","account","envelope"],"description":"What it watches: a `category`, an `account` or an `envelope` of money set aside."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category (and its subcategories) this budget watches."},"account":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The financial account this budget is limited to."},"month":{"type":"string","description":"The month these figures are for, YYYY-MM."},"rolloverMode":{"type":"string","enum":["none","carry","buffer"],"description":"What happens to the unspent amount at month end: nothing, carry it forward, or hold it in a buffer."},"alertThresholdPercent":{"description":"Warn at this percentage of the budget used; null for no alert.","type":["integer","null"]},"archived":{"type":"boolean","description":"True once the budget has been archived."},"version":{"type":"string","description":"Send as `If-Match` when editing the budget."},"progressPercent":{"type":"integer","description":"Spent as a percentage of what was available to spend this month."},"status":{"type":"string","enum":["under","near","over"],"description":"`under` while there is room, `near` once the alert threshold is reached, `over` once everything available is spent."},"plannedMinor":{"type":"integer","description":"Amount planned for the month, in whole pence."},"plannedDisplay":{"type":"string","description":"Amount planned for the month, ready to show, such as £12.50."},"openingMinor":{"type":"integer","description":"Amount carried in from earlier months, in whole pence."},"openingDisplay":{"type":"string","description":"Amount carried in from earlier months, ready to show, such as £12.50."},"fundingMinor":{"type":"integer","description":"Amount added to the budget this month, in whole pence."},"fundingDisplay":{"type":"string","description":"Amount added to the budget this month, ready to show, such as £12.50."},"bufferDrawMinor":{"type":"integer","description":"Amount taken from the buffer to cover overspending, in whole pence."},"bufferDrawDisplay":{"type":"string","description":"Amount taken from the buffer to cover overspending, ready to show, such as £12.50."},"spentMinor":{"type":"integer","description":"Amount spent this month, in whole pence."},"spentDisplay":{"type":"string","description":"Amount spent this month, ready to show, such as £12.50."},"remainingMinor":{"type":"integer","description":"Amount left to spend; negative when over, in whole pence."},"remainingDisplay":{"type":"string","description":"Amount left to spend; negative when over, ready to show, such as £12.50."},"overLimitMinor":{"type":"integer","description":"Amount spent beyond what was available, in whole pence."},"overLimitDisplay":{"type":"string","description":"Amount spent beyond what was available, ready to show, such as £12.50."},"bufferMinor":{"type":"integer","description":"Amount held in the buffer, in whole pence."},"bufferDisplay":{"type":"string","description":"Amount held in the buffer, ready to show, such as £12.50."},"bufferShortfallMinor":{"type":"integer","description":"Amount the buffer is short of what it should hold, in whole pence."},"bufferShortfallDisplay":{"type":"string","description":"Amount the buffer is short of what it should hold, ready to show, such as £12.50."},"history":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"The month these figures are for, YYYY-MM."},"progressPercent":{"type":"integer","description":"Spent as a percentage of what was available to spend this month."},"status":{"type":"string","enum":["under","near","over"],"description":"`under` while there is room, `near` once the alert threshold is reached, `over` once everything available is spent."},"plannedMinor":{"type":"integer","description":"Amount planned for the month, in whole pence."},"plannedDisplay":{"type":"string","description":"Amount planned for the month, ready to show, such as £12.50."},"openingMinor":{"type":"integer","description":"Amount carried in from earlier months, in whole pence."},"openingDisplay":{"type":"string","description":"Amount carried in from earlier months, ready to show, such as £12.50."},"fundingMinor":{"type":"integer","description":"Amount added to the budget this month, in whole pence."},"fundingDisplay":{"type":"string","description":"Amount added to the budget this month, ready to show, such as £12.50."},"bufferDrawMinor":{"type":"integer","description":"Amount taken from the buffer to cover overspending, in whole pence."},"bufferDrawDisplay":{"type":"string","description":"Amount taken from the buffer to cover overspending, ready to show, such as £12.50."},"spentMinor":{"type":"integer","description":"Amount spent this month, in whole pence."},"spentDisplay":{"type":"string","description":"Amount spent this month, ready to show, such as £12.50."},"remainingMinor":{"type":"integer","description":"Amount left to spend; negative when over, in whole pence."},"remainingDisplay":{"type":"string","description":"Amount left to spend; negative when over, ready to show, such as £12.50."},"overLimitMinor":{"type":"integer","description":"Amount spent beyond what was available, in whole pence."},"overLimitDisplay":{"type":"string","description":"Amount spent beyond what was available, ready to show, such as £12.50."},"bufferMinor":{"type":"integer","description":"Amount held in the buffer, in whole pence."},"bufferDisplay":{"type":"string","description":"Amount held in the buffer, ready to show, such as £12.50."},"bufferShortfallMinor":{"type":"integer","description":"Amount the buffer is short of what it should hold, in whole pence."},"bufferShortfallDisplay":{"type":"string","description":"Amount the buffer is short of what it should hold, ready to show, such as £12.50."}},"required":["month","progressPercent","status","plannedMinor","plannedDisplay","openingMinor","openingDisplay","fundingMinor","fundingDisplay","bufferDrawMinor","bufferDrawDisplay","spentMinor","spentDisplay","remainingMinor","remainingDisplay","overLimitMinor","overLimitDisplay","bufferMinor","bufferDisplay","bufferShortfallMinor","bufferShortfallDisplay"],"additionalProperties":false},"description":"The earlier months, with the same figures for each."}},"required":["id","name","scope","category","account","month","rolloverMode","alertThresholdPercent","archived","version","progressPercent","status","plannedMinor","plannedDisplay","openingMinor","openingDisplay","fundingMinor","fundingDisplay","bufferDrawMinor","bufferDrawDisplay","spentMinor","spentDisplay","remainingMinor","remainingDisplay","overLimitMinor","overLimitDisplay","bufferMinor","bufferDisplay","bufferShortfallMinor","bufferShortfallDisplay","history"],"additionalProperties":false}}},"example":{"data":{"id":"bud_groceries","name":"Groceries","scope":"category","category":{"id":"cat_groceries","name":"Groceries"},"account":null,"month":"2026-11","plannedMinor":42500,"plannedDisplay":"£425.00","openingMinor":0,"openingDisplay":"£0.00","fundingMinor":0,"fundingDisplay":"£0.00","bufferDrawMinor":0,"bufferDrawDisplay":"£0.00","spentMinor":31250,"spentDisplay":"£312.50","remainingMinor":8750,"remainingDisplay":"£87.50","overLimitMinor":0,"overLimitDisplay":"£0.00","bufferMinor":0,"bufferDisplay":"£0.00","bufferShortfallMinor":0,"bufferShortfallDisplay":"£0.00","progressPercent":78,"status":"near","rolloverMode":"none","alertThresholdPercent":75,"archived":false,"version":"1792000000000","history":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`conflict`: The budget is archived (`reason: budget_archived`).\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/goals":{"get":{"operationId":"getGoals","tags":["goals"],"summary":"List goals","description":"Savings and payoff goals with their progress. `progress` is what the Goals page shows: for a savings goal the cash set aside for it that the account still covers, for a payoff goal the debt repaid since it began; never above the target. `shortfall` is what is still missing, `reserved` is the cash earmarked for the goal, and `requiredPerMonth` is the even monthly amount needed to meet the deadline (null without one). Archived goals are hidden unless `archived=include|only`. The `meta` block totals the cash reserved across active goals and how much of it the accounts still cover. To keep a copy in step, send `updatedSince`: only goals edited since then come back, archived ones included and flagged. A goal counts as edited when the goal itself changes; its `progress` moves with your transactions and funding without that, so refresh the figures you show.\n\nNeeds the `goals:read` scope.","x-required-scope":"goals:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"archived","in":"query","required":false,"description":"Archived items: `exclude` (default), `include` or `only`. With `updatedSince` the default is `include`, so a change to archived shows.","schema":{"type":"string","enum":["exclude","include","only"]}},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The goal id."},"name":{"type":"string","description":"The goal name."},"type":{"type":"string","enum":["savings","payoff"],"description":"`savings` builds towards a target; `payoff` clears a debt."},"progressPercent":{"type":"integer","description":"Progress as a whole percentage of the target."},"deadline":{"description":"Calendar day, YYYY-MM-DD.","type":["string","null"]},"deadlineStatus":{"type":"string","enum":["none","future","due","overdue","met"],"description":"How the deadline stands: `none` when there is no deadline, `future`, `due` today, `overdue`, or `met` once the target is reached."},"remainingDays":{"description":"Days to the deadline; negative once it has passed.","type":["integer","null"]},"account":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account the goal is measured on.","additionalProperties":false},"fundingAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The cash account a payoff goal is funded from."},"archived":{"type":"boolean","description":"True once the goal has been archived."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or archiving the goal."},"targetMinor":{"type":"integer","description":"The amount to reach, in whole pence."},"targetDisplay":{"type":"string","description":"The amount to reach, ready to show, such as £12.50."},"progressMinor":{"type":"integer","description":"The amount reached so far, in whole pence."},"progressDisplay":{"type":"string","description":"The amount reached so far, ready to show, such as £12.50."},"shortfallMinor":{"type":"integer","description":"The amount still to find, in whole pence."},"shortfallDisplay":{"type":"string","description":"The amount still to find, ready to show, such as £12.50."},"reservedMinor":{"type":"integer","description":"The amount set aside for it so far, in whole pence."},"reservedDisplay":{"type":"string","description":"The amount set aside for it so far, ready to show, such as £12.50."},"outstandingDebtMinor":{"type":"integer","description":"For a payoff goal, the debt still owed, in whole pence."},"outstandingDebtDisplay":{"type":"string","description":"For a payoff goal, the debt still owed, ready to show, such as £12.50."},"requiredPerMonthMinor":{"description":"What to put aside each month to meet the deadline, in whole pence; null when there is none.","type":["integer","null"]},"requiredPerMonthDisplay":{"description":"What to put aside each month to meet the deadline, ready to show, such as £12.50; null when there is none.","type":["string","null"]}},"required":["id","name","type","progressPercent","deadline","deadlineStatus","remainingDays","account","fundingAccount","archived","createdAt","version","targetMinor","targetDisplay","progressMinor","progressDisplay","shortfallMinor","shortfallDisplay","reservedMinor","reservedDisplay","outstandingDebtMinor","outstandingDebtDisplay","requiredPerMonthMinor","requiredPerMonthDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"goal_holiday","name":"Summer holiday","type":"savings","targetMinor":150000,"targetDisplay":"£1,500.00","progressMinor":60000,"progressDisplay":"£600.00","progressPercent":40,"shortfallMinor":90000,"shortfallDisplay":"£900.00","reservedMinor":60000,"reservedDisplay":"£600.00","outstandingDebtMinor":0,"outstandingDebtDisplay":"£0.00","requiredPerMonthMinor":30000,"requiredPerMonthDisplay":"£300.00","deadline":"2027-03-01","deadlineStatus":"future","remainingDays":126,"account":{"id":"acc_savings","name":"Holiday pot"},"fundingAccount":null,"archived":false,"createdAt":"2026-09-01T10:00:00.000Z","version":"1792000000000"}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postGoals","tags":["goals"],"summary":"Create a goal","description":"Creates a savings or payoff goal. A savings goal is measured on a cash or savings account; a payoff goal on a credit account that currently owes money, and may name a cash account to fund it. The answer is the goal as `GET /goals/{id}` shows it.\n\nNeeds the `goals:write` scope.","x-required-scope":"goals:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":160,"description":"The goal name."},"type":{"type":"string","enum":["savings","payoff"],"description":"`savings` sets cash aside in a cash or savings account; `payoff` repays the debt on a credit account."},"targetMinor":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647,"description":"The target in pence. For a payoff goal it cannot exceed the debt now."},"deadline":{"description":"The day to reach the target by, `YYYY-MM-DD`. Null for no deadline.","type":["string","null"]},"accountId":{"type":"string","minLength":1,"description":"The account the goal is measured on: where savings are held, or the credit account to pay off."},"fundingAccountId":{"description":"For a payoff goal, the cash account its reserved money comes from.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["name","type","targetMinor","accountId"],"additionalProperties":false},"example":{"name":"Summer holiday","type":"savings","targetMinor":150000,"deadline":"2027-03-01","accountId":"acc_savings"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The goal id."},"name":{"type":"string","description":"The goal name."},"type":{"type":"string","enum":["savings","payoff"],"description":"`savings` builds towards a target; `payoff` clears a debt."},"progressPercent":{"type":"integer","description":"Progress as a whole percentage of the target."},"deadline":{"description":"Calendar day, YYYY-MM-DD.","type":["string","null"]},"deadlineStatus":{"type":"string","enum":["none","future","due","overdue","met"],"description":"How the deadline stands: `none` when there is no deadline, `future`, `due` today, `overdue`, or `met` once the target is reached."},"remainingDays":{"description":"Days to the deadline; negative once it has passed.","type":["integer","null"]},"account":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account the goal is measured on.","additionalProperties":false},"fundingAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The cash account a payoff goal is funded from."},"archived":{"type":"boolean","description":"True once the goal has been archived."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or archiving the goal."},"targetMinor":{"type":"integer","description":"The amount to reach, in whole pence."},"targetDisplay":{"type":"string","description":"The amount to reach, ready to show, such as £12.50."},"progressMinor":{"type":"integer","description":"The amount reached so far, in whole pence."},"progressDisplay":{"type":"string","description":"The amount reached so far, ready to show, such as £12.50."},"shortfallMinor":{"type":"integer","description":"The amount still to find, in whole pence."},"shortfallDisplay":{"type":"string","description":"The amount still to find, ready to show, such as £12.50."},"reservedMinor":{"type":"integer","description":"The amount set aside for it so far, in whole pence."},"reservedDisplay":{"type":"string","description":"The amount set aside for it so far, ready to show, such as £12.50."},"outstandingDebtMinor":{"type":"integer","description":"For a payoff goal, the debt still owed, in whole pence."},"outstandingDebtDisplay":{"type":"string","description":"For a payoff goal, the debt still owed, ready to show, such as £12.50."},"requiredPerMonthMinor":{"description":"What to put aside each month to meet the deadline, in whole pence; null when there is none.","type":["integer","null"]},"requiredPerMonthDisplay":{"description":"What to put aside each month to meet the deadline, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"funding":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The funding entry id."},"occurredOn":{"type":"string","description":"The day the money was put towards the goal, YYYY-MM-DD."},"note":{"description":"A short note.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"amountMinor":{"type":"integer","description":"The amount put towards the goal, in whole pence."},"amountDisplay":{"type":"string","description":"The amount put towards the goal, ready to show, such as £12.50."}},"required":["id","occurredOn","note","createdAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Money put towards the goal, newest first."}},"required":["id","name","type","progressPercent","deadline","deadlineStatus","remainingDays","account","fundingAccount","archived","createdAt","version","targetMinor","targetDisplay","progressMinor","progressDisplay","shortfallMinor","shortfallDisplay","reservedMinor","reservedDisplay","outstandingDebtMinor","outstandingDebtDisplay","requiredPerMonthMinor","requiredPerMonthDisplay","funding"],"additionalProperties":false}}},"example":{"data":{"id":"goal_holiday","name":"Summer holiday","type":"savings","targetMinor":150000,"targetDisplay":"£1,500.00","progressMinor":0,"progressDisplay":"£0.00","progressPercent":0,"shortfallMinor":90000,"shortfallDisplay":"£900.00","reservedMinor":0,"reservedDisplay":"£0.00","outstandingDebtMinor":0,"outstandingDebtDisplay":"£0.00","requiredPerMonthMinor":30000,"requiredPerMonthDisplay":"£300.00","deadline":"2027-03-01","deadlineStatus":"future","remainingDays":126,"account":{"id":"acc_savings","name":"Holiday pot"},"fundingAccount":null,"archived":false,"createdAt":"2026-09-01T10:00:00.000Z","version":"1792000000000","funding":[]}}}}},"400":{"description":"`validation_failed`: A savings goal is on a credit account, or a payoff goal is on an account that owes nothing. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The account or funding account does not exist or belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/goals/{id}":{"get":{"operationId":"getGoalsById","tags":["goals"],"summary":"Get a goal","description":"One goal with its funding history, oldest first. `progress` is what the Goals page shows: for a savings goal the cash set aside for it that the account still covers, for a payoff goal the debt repaid since it began; never above the target. `shortfall` is what is still missing, `reserved` is the cash earmarked for the goal, and `requiredPerMonth` is the even monthly amount needed to meet the deadline (null without one). A funding entry's amount is negative when money was taken back out of the goal.\n\nNeeds the `goals:read` scope.","x-required-scope":"goals:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The goal id.","schema":{"type":"string","minLength":1},"example":"goal_holiday"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The goal id."},"name":{"type":"string","description":"The goal name."},"type":{"type":"string","enum":["savings","payoff"],"description":"`savings` builds towards a target; `payoff` clears a debt."},"progressPercent":{"type":"integer","description":"Progress as a whole percentage of the target."},"deadline":{"description":"Calendar day, YYYY-MM-DD.","type":["string","null"]},"deadlineStatus":{"type":"string","enum":["none","future","due","overdue","met"],"description":"How the deadline stands: `none` when there is no deadline, `future`, `due` today, `overdue`, or `met` once the target is reached."},"remainingDays":{"description":"Days to the deadline; negative once it has passed.","type":["integer","null"]},"account":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account the goal is measured on.","additionalProperties":false},"fundingAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The cash account a payoff goal is funded from."},"archived":{"type":"boolean","description":"True once the goal has been archived."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or archiving the goal."},"targetMinor":{"type":"integer","description":"The amount to reach, in whole pence."},"targetDisplay":{"type":"string","description":"The amount to reach, ready to show, such as £12.50."},"progressMinor":{"type":"integer","description":"The amount reached so far, in whole pence."},"progressDisplay":{"type":"string","description":"The amount reached so far, ready to show, such as £12.50."},"shortfallMinor":{"type":"integer","description":"The amount still to find, in whole pence."},"shortfallDisplay":{"type":"string","description":"The amount still to find, ready to show, such as £12.50."},"reservedMinor":{"type":"integer","description":"The amount set aside for it so far, in whole pence."},"reservedDisplay":{"type":"string","description":"The amount set aside for it so far, ready to show, such as £12.50."},"outstandingDebtMinor":{"type":"integer","description":"For a payoff goal, the debt still owed, in whole pence."},"outstandingDebtDisplay":{"type":"string","description":"For a payoff goal, the debt still owed, ready to show, such as £12.50."},"requiredPerMonthMinor":{"description":"What to put aside each month to meet the deadline, in whole pence; null when there is none.","type":["integer","null"]},"requiredPerMonthDisplay":{"description":"What to put aside each month to meet the deadline, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"funding":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The funding entry id."},"occurredOn":{"type":"string","description":"The day the money was put towards the goal, YYYY-MM-DD."},"note":{"description":"A short note.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"amountMinor":{"type":"integer","description":"The amount put towards the goal, in whole pence."},"amountDisplay":{"type":"string","description":"The amount put towards the goal, ready to show, such as £12.50."}},"required":["id","occurredOn","note","createdAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Money put towards the goal, newest first."}},"required":["id","name","type","progressPercent","deadline","deadlineStatus","remainingDays","account","fundingAccount","archived","createdAt","version","targetMinor","targetDisplay","progressMinor","progressDisplay","shortfallMinor","shortfallDisplay","reservedMinor","reservedDisplay","outstandingDebtMinor","outstandingDebtDisplay","requiredPerMonthMinor","requiredPerMonthDisplay","funding"],"additionalProperties":false}}},"example":{"data":{"id":"goal_holiday","name":"Summer holiday","type":"savings","targetMinor":150000,"targetDisplay":"£1,500.00","progressMinor":60000,"progressDisplay":"£600.00","progressPercent":40,"shortfallMinor":90000,"shortfallDisplay":"£900.00","reservedMinor":60000,"reservedDisplay":"£600.00","outstandingDebtMinor":0,"outstandingDebtDisplay":"£0.00","requiredPerMonthMinor":30000,"requiredPerMonthDisplay":"£300.00","deadline":"2027-03-01","deadlineStatus":"future","remainingDays":126,"account":{"id":"acc_savings","name":"Holiday pot"},"fundingAccount":null,"archived":false,"createdAt":"2026-09-01T10:00:00.000Z","version":"1792000000000","funding":[{"id":"fund_1","occurredOn":"2026-09-15","amountMinor":60000,"amountDisplay":"£600.00","note":"From the bonus","createdAt":"2026-09-15T08:00:00.000Z"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"patchGoalsById","tags":["goals"],"summary":"Edit, archive or restore a goal","description":"Changes the fields you send and leaves the rest. A goal that has reserved funds cannot change its type or account, and its target cannot drop below what is reserved. An archived goal must be restored (`archived: false`) before it can be edited; both can be sent together. Send the `version` you last read as `If-Match` (or in the body): if the goal has changed since, the answer is 412 `version_conflict`. A restore is applied first, then the edits, then an archive; if a later step is refused, the earlier ones stay.\n\nNeeds the `goals:write` scope.","x-required-scope":"goals:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The goal id.","schema":{"type":"string","minLength":1},"example":"goal_holiday"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"A new name.","type":"string","minLength":1,"maxLength":160},"type":{"description":"Changing the type needs the goal to have no reserved funds.","type":"string","enum":["savings","payoff"]},"targetMinor":{"description":"A new target in pence; it cannot be below what is reserved.","type":"integer","exclusiveMinimum":0,"maximum":2147483647},"deadline":{"description":"The day to reach the target by, `YYYY-MM-DD`. Null for no deadline.","type":["string","null"]},"accountId":{"description":"Measure on a different account; needs no reserved funds.","type":"string","minLength":1},"fundingAccountId":{"description":"A payoff goal's funding account.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"archived":{"description":"True archives the goal; false restores it (the account must cover its reserve).","type":"boolean"},"version":{"description":"The `version` you last read, as an alternative to the `If-Match` header.","type":"string"}},"additionalProperties":false},"example":{"targetMinor":180000,"deadline":"2027-04-01"}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The goal id."},"name":{"type":"string","description":"The goal name."},"type":{"type":"string","enum":["savings","payoff"],"description":"`savings` builds towards a target; `payoff` clears a debt."},"progressPercent":{"type":"integer","description":"Progress as a whole percentage of the target."},"deadline":{"description":"Calendar day, YYYY-MM-DD.","type":["string","null"]},"deadlineStatus":{"type":"string","enum":["none","future","due","overdue","met"],"description":"How the deadline stands: `none` when there is no deadline, `future`, `due` today, `overdue`, or `met` once the target is reached."},"remainingDays":{"description":"Days to the deadline; negative once it has passed.","type":["integer","null"]},"account":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account the goal is measured on.","additionalProperties":false},"fundingAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The cash account a payoff goal is funded from."},"archived":{"type":"boolean","description":"True once the goal has been archived."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or archiving the goal."},"targetMinor":{"type":"integer","description":"The amount to reach, in whole pence."},"targetDisplay":{"type":"string","description":"The amount to reach, ready to show, such as £12.50."},"progressMinor":{"type":"integer","description":"The amount reached so far, in whole pence."},"progressDisplay":{"type":"string","description":"The amount reached so far, ready to show, such as £12.50."},"shortfallMinor":{"type":"integer","description":"The amount still to find, in whole pence."},"shortfallDisplay":{"type":"string","description":"The amount still to find, ready to show, such as £12.50."},"reservedMinor":{"type":"integer","description":"The amount set aside for it so far, in whole pence."},"reservedDisplay":{"type":"string","description":"The amount set aside for it so far, ready to show, such as £12.50."},"outstandingDebtMinor":{"type":"integer","description":"For a payoff goal, the debt still owed, in whole pence."},"outstandingDebtDisplay":{"type":"string","description":"For a payoff goal, the debt still owed, ready to show, such as £12.50."},"requiredPerMonthMinor":{"description":"What to put aside each month to meet the deadline, in whole pence; null when there is none.","type":["integer","null"]},"requiredPerMonthDisplay":{"description":"What to put aside each month to meet the deadline, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"funding":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The funding entry id."},"occurredOn":{"type":"string","description":"The day the money was put towards the goal, YYYY-MM-DD."},"note":{"description":"A short note.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"amountMinor":{"type":"integer","description":"The amount put towards the goal, in whole pence."},"amountDisplay":{"type":"string","description":"The amount put towards the goal, ready to show, such as £12.50."}},"required":["id","occurredOn","note","createdAt","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Money put towards the goal, newest first."}},"required":["id","name","type","progressPercent","deadline","deadlineStatus","remainingDays","account","fundingAccount","archived","createdAt","version","targetMinor","targetDisplay","progressMinor","progressDisplay","shortfallMinor","shortfallDisplay","reservedMinor","reservedDisplay","outstandingDebtMinor","outstandingDebtDisplay","requiredPerMonthMinor","requiredPerMonthDisplay","funding"],"additionalProperties":false}}},"example":{"data":{"id":"goal_holiday","name":"Summer holiday","type":"savings","targetMinor":180000,"targetDisplay":"£1,800.00","progressMinor":60000,"progressDisplay":"£600.00","progressPercent":40,"shortfallMinor":90000,"shortfallDisplay":"£900.00","reservedMinor":60000,"reservedDisplay":"£600.00","outstandingDebtMinor":0,"outstandingDebtDisplay":"£0.00","requiredPerMonthMinor":30000,"requiredPerMonthDisplay":"£300.00","deadline":"2027-04-01","deadlineStatus":"future","remainingDays":126,"account":{"id":"acc_savings","name":"Holiday pot"},"fundingAccount":null,"archived":false,"createdAt":"2026-09-01T10:00:00.000Z","version":"1792000000000","funding":[]}}}}},"400":{"description":"`validation_failed`: The body is empty, the type or account changes while funds are reserved, or the target drops below what is reserved. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The account or funding account does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/goals/{id}/funding":{"post":{"operationId":"postGoalsByIdFunding","tags":["goals"],"summary":"Reserve or release money for a goal","description":"Adds a funding entry: a positive `amountMinor` (pence) sets cash aside for the goal, a negative one releases it. Nothing moves between accounts; the money stays where it is and is reserved on paper. It needs enough unreserved cash in the funding account, cannot take the reserve above the target or below zero, and `date` cannot be in the future. Archived goals cannot be funded. The answer is the new entry, with the goal as it now stands.\n\nNeeds the `goals:write` scope.","x-required-scope":"goals:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The goal id.","schema":{"type":"string","minLength":1},"example":"goal_holiday"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":-2147483647,"maximum":2147483647,"description":"Pence to reserve (positive) or release (negative)."},"date":{"description":"The day the money was set aside, `YYYY-MM-DD`, today or earlier.","type":"string"},"note":{"description":"A short note shown in the goal's history.","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]}},"required":["amountMinor","date"],"additionalProperties":false},"example":{"amountMinor":25000,"date":"2026-10-24","note":"From the bonus"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The funding entry id."},"occurredOn":{"type":"string","description":"The day the money was put towards the goal, YYYY-MM-DD."},"note":{"description":"A short note.","type":["string","null"]},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"amountMinor":{"type":"integer","description":"The amount put towards the goal, in whole pence."},"amountDisplay":{"type":"string","description":"The amount put towards the goal, ready to show, such as £12.50."},"goal":{"type":"object","properties":{"id":{"type":"string","description":"The goal id."},"name":{"type":"string","description":"The goal name."},"type":{"type":"string","enum":["savings","payoff"],"description":"`savings` builds towards a target; `payoff` clears a debt."},"progressPercent":{"type":"integer","description":"Progress as a whole percentage of the target."},"deadline":{"description":"Calendar day, YYYY-MM-DD.","type":["string","null"]},"deadlineStatus":{"type":"string","enum":["none","future","due","overdue","met"],"description":"How the deadline stands: `none` when there is no deadline, `future`, `due` today, `overdue`, or `met` once the target is reached."},"remainingDays":{"description":"Days to the deadline; negative once it has passed.","type":["integer","null"]},"account":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"description":"The account the goal is measured on.","additionalProperties":false},"fundingAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The cash account a payoff goal is funded from."},"archived":{"type":"boolean","description":"True once the goal has been archived."},"createdAt":{"description":"When it was created, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Send as `If-Match` when editing or archiving the goal."},"targetMinor":{"type":"integer","description":"The amount to reach, in whole pence."},"targetDisplay":{"type":"string","description":"The amount to reach, ready to show, such as £12.50."},"progressMinor":{"type":"integer","description":"The amount reached so far, in whole pence."},"progressDisplay":{"type":"string","description":"The amount reached so far, ready to show, such as £12.50."},"shortfallMinor":{"type":"integer","description":"The amount still to find, in whole pence."},"shortfallDisplay":{"type":"string","description":"The amount still to find, ready to show, such as £12.50."},"reservedMinor":{"type":"integer","description":"The amount set aside for it so far, in whole pence."},"reservedDisplay":{"type":"string","description":"The amount set aside for it so far, ready to show, such as £12.50."},"outstandingDebtMinor":{"type":"integer","description":"For a payoff goal, the debt still owed, in whole pence."},"outstandingDebtDisplay":{"type":"string","description":"For a payoff goal, the debt still owed, ready to show, such as £12.50."},"requiredPerMonthMinor":{"description":"What to put aside each month to meet the deadline, in whole pence; null when there is none.","type":["integer","null"]},"requiredPerMonthDisplay":{"description":"What to put aside each month to meet the deadline, ready to show, such as £12.50; null when there is none.","type":["string","null"]}},"required":["id","name","type","progressPercent","deadline","deadlineStatus","remainingDays","account","fundingAccount","archived","createdAt","version","targetMinor","targetDisplay","progressMinor","progressDisplay","shortfallMinor","shortfallDisplay","reservedMinor","reservedDisplay","outstandingDebtMinor","outstandingDebtDisplay","requiredPerMonthMinor","requiredPerMonthDisplay"],"description":"The goal after the change.","additionalProperties":false}},"required":["id","occurredOn","note","createdAt","amountMinor","amountDisplay","goal"],"additionalProperties":false}}},"example":{"data":{"id":"fund_2","occurredOn":"2026-10-24","amountMinor":25000,"amountDisplay":"£250.00","note":"From the bonus","createdAt":"2026-10-24T08:00:00.000Z","goal":{"id":"goal_holiday","name":"Summer holiday","type":"savings","targetMinor":150000,"targetDisplay":"£1,500.00","progressMinor":60000,"progressDisplay":"£600.00","progressPercent":40,"shortfallMinor":90000,"shortfallDisplay":"£900.00","reservedMinor":60000,"reservedDisplay":"£600.00","outstandingDebtMinor":0,"outstandingDebtDisplay":"£0.00","requiredPerMonthMinor":30000,"requiredPerMonthDisplay":"£300.00","deadline":"2027-03-01","deadlineStatus":"future","remainingDays":126,"account":{"id":"acc_savings","name":"Holiday pot"},"fundingAccount":null,"archived":false,"createdAt":"2026-09-01T10:00:00.000Z","version":"1792000000000"}}}}}},"400":{"description":"`validation_failed`: The funding account lacks enough unreserved cash, the reserve would pass the target or drop below zero, the goal is archived, or `date` is in the future. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/insights/totals":{"get":{"operationId":"getInsightsTotals","tags":["insights"],"summary":"Income, spending and net for a range","description":"Income, spending and net between two dates, optionally split by day, week (Monday to Sunday) or month. Transfers between your own accounts are left out; refunds and other adjustments reduce the side they belong to. Days are UK calendar days. Every group in the range is listed, empty ones as zero, and the first and last are cut to the range. `meta.total` is worked out over the whole range. Also open to keys that only have the narrow `totals:read` scope.\n\nNeeds the `totals:read` scope.","x-required-scope":"totals:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Start of the range: `YYYY-MM-DD` (that whole UK day) or an ISO 8601 timestamp. Default: 29 days before `to`.","schema":{"type":"string"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"End of the range, included: `YYYY-MM-DD` (that whole UK day) or an ISO 8601 timestamp. Default: today.","schema":{"type":"string"},"example":"2026-10-31"},{"name":"groupBy","in":"query","required":false,"description":"How to split the range: `day`, `week`, `month` or `none` (one group, the default).","schema":{"default":"none","type":"string","enum":["day","week","month","none"]},"example":"month"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"First UK day of the group inside the range."},"end":{"type":"string","description":"Last UK day of the group inside the range."},"lineCount":{"type":"integer","description":"Ledger lines counted."},"incomeMinor":{"type":"integer","description":"Income, in whole pence."},"incomeDisplay":{"type":"string","description":"Income, ready to show, such as £12.50."},"spendingMinor":{"type":"integer","description":"Spending, in whole pence."},"spendingDisplay":{"type":"string","description":"Spending, ready to show, such as £12.50."},"netMinor":{"type":"integer","description":"Net, in whole pence."},"netDisplay":{"type":"string","description":"Net, ready to show, such as £12.50."}},"required":["start","end","lineCount","incomeMinor","incomeDisplay","spendingMinor","spendingDisplay","netMinor","netDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"start":"2026-10-01","end":"2026-10-31","incomeMinor":320000,"incomeDisplay":"£3,200.00","spendingMinor":187450,"spendingDisplay":"£1,874.50","netMinor":132550,"netDisplay":"£1,325.50","lineCount":64}],"page":{"nextCursor":null,"hasMore":false}}}}},"400":{"description":"`validation_failed`: `from` is after `to`, the range is longer than 3,660 days, or `groupBy=day` covers more than 366 days. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/insights/cash-flow":{"get":{"operationId":"getInsightsCashFlow","tags":["insights"],"summary":"Cash flow over time","description":"The dashboard's cash flow chart as data: income, spending, net and the running balance of all accounts, one row per day, week or month. Transfers between your own accounts are not counted as flow. `balance` is the balance at the end of the row. The range is whole UK days.\n\nNeeds the `insights:read` scope.","x-required-scope":"insights:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Start of the range: `YYYY-MM-DD` (that whole UK day) or an ISO 8601 timestamp. Default: 29 days before `to`.","schema":{"type":"string"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"End of the range, included: `YYYY-MM-DD` (that whole UK day) or an ISO 8601 timestamp. Default: today.","schema":{"type":"string"},"example":"2026-10-31"},{"name":"interval","in":"query","required":false,"description":"One row per `day` (the default), `week` (Monday to Sunday) or `month`.","schema":{"default":"day","type":"string","enum":["day","week","month"]},"example":"week"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"First UK day of the point inside the range."},"end":{"type":"string","description":"Last UK day of the point inside the range."},"lineCount":{"type":"integer","description":"Ledger lines counted."},"incomeMinor":{"type":"integer","description":"Income, in whole pence."},"incomeDisplay":{"type":"string","description":"Income, ready to show, such as £12.50."},"spendingMinor":{"type":"integer","description":"Spending, in whole pence."},"spendingDisplay":{"type":"string","description":"Spending, ready to show, such as £12.50."},"netMinor":{"type":"integer","description":"Net, in whole pence."},"netDisplay":{"type":"string","description":"Net, ready to show, such as £12.50."},"balanceMinor":{"type":"integer","description":"Balance of all accounts at the end of the point, in whole pence."},"balanceDisplay":{"type":"string","description":"Balance of all accounts at the end of the point, ready to show, such as £12.50."}},"required":["start","end","lineCount","incomeMinor","incomeDisplay","spendingMinor","spendingDisplay","netMinor","netDisplay","balanceMinor","balanceDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"start":"2026-10-01","end":"2026-10-04","incomeMinor":0,"incomeDisplay":"£0.00","spendingMinor":4210,"spendingDisplay":"£42.10","netMinor":-4210,"netDisplay":"-£42.10","balanceMinor":215790,"balanceDisplay":"£2,157.90","lineCount":3}],"page":{"nextCursor":null,"hasMore":false}}}}},"400":{"description":"`validation_failed`: `from` is after `to`, the range is longer than 3,660 days, or daily rows cover more than 366 days. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/insights/spending":{"get":{"operationId":"getInsightsSpending","tags":["insights"],"summary":"Where the money went","description":"The dashboard's spending breakdown: the biggest categories or payees by money spent in the range, largest first. Transfers between your own accounts are not counted; refunds reduce what was spent. `meta.others` adds up everything below `limit`. `sharePercent` is the row’s part of `meta.totalSpending`, which counts every category (or payee) with spending in the range, not only the rows returned, so the shares of the returned rows add up to less than 100 when `meta.others` is not empty. Spending with no category (or no payee) is one row with `id: null` and the name `Uncategorised` (or `No payee`). The range is whole UK days.\n\nNeeds the `insights:read` scope.","x-required-scope":"insights:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Start of the range: `YYYY-MM-DD` (that whole UK day) or an ISO 8601 timestamp. Default: 29 days before `to`.","schema":{"type":"string"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"End of the range, included: `YYYY-MM-DD` (that whole UK day) or an ISO 8601 timestamp. Default: today.","schema":{"type":"string"},"example":"2026-10-31"},{"name":"by","in":"query","required":false,"description":"Group by `category` (the default) or `payee`.","schema":{"default":"category","type":"string","enum":["category","payee"]},"example":"category"},{"name":"limit","in":"query","required":false,"description":"How many rows, 1 to 100. Default 10.","schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"example":"5"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The category or payee id; null for spending with no category or payee.","type":["string","null"]},"name":{"type":"string","description":"The category or payee name."},"path":{"description":"The category with its parents, such as `Home › Bills`.","type":["string","null"]},"sharePercent":{"type":"number","description":"Share of `meta.totalSpending` (all spending in the range), 0 to 100, one decimal."},"lineCount":{"type":"integer","description":"Ledger lines counted."},"spendingMinor":{"type":"integer","description":"Spending, in whole pence."},"spendingDisplay":{"type":"string","description":"Spending, ready to show, such as £12.50."}},"required":["id","name","path","sharePercent","lineCount","spendingMinor","spendingDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"cat_1","name":"Groceries","path":"Food › Groceries","spendingMinor":41230,"spendingDisplay":"£412.30","sharePercent":22,"lineCount":18}],"page":{"nextCursor":null,"hasMore":false}}}}},"400":{"description":"`validation_failed`: `from` is after `to`, or the range is longer than 3,660 days. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/insights/net-worth":{"get":{"operationId":"getInsightsNetWorth","tags":["insights"],"summary":"Net worth and how it changed","description":"The dashboard's net worth card: the balance of all accounts at the end of `to` (today by default), what it was before `from`, and the change between. Credit cards count as negative balances. For the day-by-day line use `/insights/cash-flow`, whose `balance` is the same figure.\n\nNeeds the `insights:read` scope.","x-required-scope":"insights:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Start of the range: `YYYY-MM-DD` (that whole UK day) or an ISO 8601 timestamp. Default: 29 days before `to`.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"End of the range, included: `YYYY-MM-DD` (that whole UK day) or an ISO 8601 timestamp. Default: today.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"from":{"type":"string","description":"The day the change is measured from."},"asOf":{"type":"string","description":"The balance is as at the end of this day."},"netWorthMinor":{"type":"integer","description":"Net worth, in whole pence."},"netWorthDisplay":{"type":"string","description":"Net worth, ready to show, such as £12.50."},"openingNetWorthMinor":{"type":"integer","description":"Opening net worth, in whole pence."},"openingNetWorthDisplay":{"type":"string","description":"Opening net worth, ready to show, such as £12.50."},"changeMinor":{"type":"integer","description":"Change, in whole pence."},"changeDisplay":{"type":"string","description":"Change, ready to show, such as £12.50."}},"required":["from","asOf","netWorthMinor","netWorthDisplay","openingNetWorthMinor","openingNetWorthDisplay","changeMinor","changeDisplay"],"additionalProperties":false}}},"example":{"data":{"from":"2026-09-27","asOf":"2026-10-26","netWorthMinor":1284050,"netWorthDisplay":"£12,840.50","openingNetWorthMinor":1251000,"openingNetWorthDisplay":"£12,510.00","changeMinor":33050,"changeDisplay":"£330.50"}}}}},"400":{"description":"`validation_failed`: `from` is after `to`, or the range is longer than 3,660 days. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/insights/forecast":{"get":{"operationId":"getInsightsForecast","tags":["insights"],"summary":"Cash forecast and safe to spend","description":"The Forecast page as data: spendable cash day by day for the next `days` days after scheduled bills and income, budgets and goal commitments, and the safe-to-spend figure. `upperAvailable` ignores possible unspent budget; `lowerAvailable` includes it. Movement amounts are signed (money out is negative). `assumptions` and `missingData` say what the numbers rest on.\n\nNeeds the `insights:read` scope.","x-required-scope":"insights:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"days","in":"query","required":false,"description":"How far ahead: 7, 14, 30, 60, 90 or 180 days. Default 30.","schema":{"default":30,"type":"number"},"example":"30"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"today":{"type":"string","description":"Today, in UK time."},"throughOn":{"type":"string","description":"The last day the forecast covers."},"budgetsEnabled":{"type":"boolean","description":"Whether budgets are switched on, so unscheduled budget spending is included."},"safeToSpend":{"type":"object","properties":{"throughOn":{"type":"string","description":"The last day counted."},"postedCashAccounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The account id."},"name":{"type":"string","description":"The account name."},"amountMinor":{"type":"integer","description":"The account balance, in whole pence."},"amountDisplay":{"type":"string","description":"The account balance, ready to show, such as £12.50."}},"required":["id","name","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The cash accounts whose posted balances are counted."},"keptAsideAccounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The account id."},"name":{"type":"string","description":"The account name."},"amountMinor":{"type":"integer","description":"The account balance, in whole pence."},"amountDisplay":{"type":"string","description":"The account balance, ready to show, such as £12.50."}},"required":["id","name","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Accounts kept aside, left out of the figures."},"startingCashMinor":{"type":"integer","description":"Starting cash, in whole pence."},"startingCashDisplay":{"type":"string","description":"Starting cash, ready to show, such as £12.50."},"excludedFutureIncomeMinor":{"type":"integer","description":"Excluded future income, in whole pence."},"excludedFutureIncomeDisplay":{"type":"string","description":"Excluded future income, ready to show, such as £12.50."},"scheduledIncomeMinor":{"type":"integer","description":"Scheduled income, in whole pence."},"scheduledIncomeDisplay":{"type":"string","description":"Scheduled income, ready to show, such as £12.50."},"scheduledExpenseMinor":{"type":"integer","description":"Scheduled expense, in whole pence."},"scheduledExpenseDisplay":{"type":"string","description":"Scheduled expense, ready to show, such as £12.50."},"reservedGoalMinor":{"type":"integer","description":"Reserved goal, in whole pence."},"reservedGoalDisplay":{"type":"string","description":"Reserved goal, ready to show, such as £12.50."},"reservedEnvelopeMinor":{"type":"integer","description":"Reserved envelope, in whole pence."},"reservedEnvelopeDisplay":{"type":"string","description":"Reserved envelope, ready to show, such as £12.50."},"envelopeReleaseMinor":{"type":"integer","description":"Envelope release, in whole pence."},"envelopeReleaseDisplay":{"type":"string","description":"Envelope release, ready to show, such as £12.50."},"unreservedCashMinor":{"type":"integer","description":"Unreserved cash, in whole pence."},"unreservedCashDisplay":{"type":"string","description":"Unreserved cash, ready to show, such as £12.50."},"keptAsideTotalMinor":{"type":"integer","description":"Kept aside total, in whole pence."},"keptAsideTotalDisplay":{"type":"string","description":"Kept aside total, ready to show, such as £12.50."},"unusedCreditMinor":{"type":"integer","description":"Unused credit, in whole pence."},"unusedCreditDisplay":{"type":"string","description":"Unused credit, ready to show, such as £12.50."},"amountMinor":{"type":"integer","description":"The safe-to-spend amount, in whole pence."},"amountDisplay":{"type":"string","description":"The safe-to-spend amount, ready to show, such as £12.50."},"shortfallMinor":{"type":"integer","description":"How much a bill goes uncovered by, if any, in whole pence."},"shortfallDisplay":{"type":"string","description":"How much a bill goes uncovered by, if any, ready to show, such as £12.50."}},"required":["throughOn","postedCashAccounts","keptAsideAccounts","startingCashMinor","startingCashDisplay","excludedFutureIncomeMinor","excludedFutureIncomeDisplay","scheduledIncomeMinor","scheduledIncomeDisplay","scheduledExpenseMinor","scheduledExpenseDisplay","reservedGoalMinor","reservedGoalDisplay","reservedEnvelopeMinor","reservedEnvelopeDisplay","envelopeReleaseMinor","envelopeReleaseDisplay","unreservedCashMinor","unreservedCashDisplay","keptAsideTotalMinor","keptAsideTotalDisplay","unusedCreditMinor","unusedCreditDisplay","amountMinor","amountDisplay","shortfallMinor","shortfallDisplay"],"description":"What can be spent without leaving a bill uncovered, and how it is made up.","additionalProperties":false},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"The day."},"movementIds":{"type":"array","items":{"type":"string"},"description":"The ids of the `movements` that land on this day."},"scheduledBalanceMinor":{"type":"integer","description":"Scheduled balance, in whole pence."},"scheduledBalanceDisplay":{"type":"string","description":"Scheduled balance, ready to show, such as £12.50."},"upperAvailableMinor":{"type":"integer","description":"Upper available, in whole pence."},"upperAvailableDisplay":{"type":"string","description":"Upper available, ready to show, such as £12.50."},"lowerAvailableMinor":{"type":"integer","description":"Lower available, in whole pence."},"lowerAvailableDisplay":{"type":"string","description":"Lower available, ready to show, such as £12.50."},"scheduledIncomeMinor":{"type":"integer","description":"Scheduled income, in whole pence."},"scheduledIncomeDisplay":{"type":"string","description":"Scheduled income, ready to show, such as £12.50."},"scheduledExpenseMinor":{"type":"integer","description":"Scheduled expense, in whole pence."},"scheduledExpenseDisplay":{"type":"string","description":"Scheduled expense, ready to show, such as £12.50."},"unscheduledBudgetMinor":{"type":"integer","description":"Unscheduled budget, in whole pence."},"unscheduledBudgetDisplay":{"type":"string","description":"Unscheduled budget, ready to show, such as £12.50."},"goalCommitmentMinor":{"type":"integer","description":"Goal commitment, in whole pence."},"goalCommitmentDisplay":{"type":"string","description":"Goal commitment, ready to show, such as £12.50."},"envelopeReleaseMinor":{"type":"integer","description":"Envelope release, in whole pence."},"envelopeReleaseDisplay":{"type":"string","description":"Envelope release, ready to show, such as £12.50."}},"required":["date","movementIds","scheduledBalanceMinor","scheduledBalanceDisplay","upperAvailableMinor","upperAvailableDisplay","lowerAvailableMinor","lowerAvailableDisplay","scheduledIncomeMinor","scheduledIncomeDisplay","scheduledExpenseMinor","scheduledExpenseDisplay","unscheduledBudgetMinor","unscheduledBudgetDisplay","goalCommitmentMinor","goalCommitmentDisplay","envelopeReleaseMinor","envelopeReleaseDisplay"],"additionalProperties":false},"description":"The projected figures for each day, soonest first."},"movements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The movement id."},"date":{"type":"string","description":"The day it lands."},"kind":{"type":"string","enum":["schedule","budget_allowance","goal_commitment"],"description":"What it is: a scheduled bill or income, a budget allowance or a goal commitment."},"scheduleKind":{"anyOf":[{"type":"string","enum":["recurring","scheduled","posted"]},{"type":"null"}],"description":"For a `schedule` movement, where it comes from; null otherwise."},"label":{"type":"string","description":"What it is called."},"amountMinor":{"type":"integer","description":"The amount of the movement; negative is money out, in whole pence."},"amountDisplay":{"type":"string","description":"The amount of the movement; negative is money out, ready to show, such as £12.50."}},"required":["id","date","kind","scheduleKind","label","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The bills, income, allowances and commitments the forecast is made of."},"assumptions":{"type":"array","items":{"type":"string"},"description":"Things the forecast assumed, in words."},"missingData":{"type":"array","items":{"type":"string"},"description":"Data that was missing, so the figures may be rough."},"startingCashMinor":{"type":"integer","description":"Starting cash, in whole pence."},"startingCashDisplay":{"type":"string","description":"Starting cash, ready to show, such as £12.50."},"scheduledIncomeMinor":{"type":"integer","description":"Scheduled income, in whole pence."},"scheduledIncomeDisplay":{"type":"string","description":"Scheduled income, ready to show, such as £12.50."},"scheduledExpenseMinor":{"type":"integer","description":"Scheduled expense, in whole pence."},"scheduledExpenseDisplay":{"type":"string","description":"Scheduled expense, ready to show, such as £12.50."},"budgetUnscheduledMinor":{"type":"integer","description":"Budget unscheduled, in whole pence."},"budgetUnscheduledDisplay":{"type":"string","description":"Budget unscheduled, ready to show, such as £12.50."},"goalCommitmentMinor":{"type":"integer","description":"Goal commitment, in whole pence."},"goalCommitmentDisplay":{"type":"string","description":"Goal commitment, ready to show, such as £12.50."},"reservedGoalMinor":{"type":"integer","description":"Reserved goal, in whole pence."},"reservedGoalDisplay":{"type":"string","description":"Reserved goal, ready to show, such as £12.50."},"reservedEnvelopeMinor":{"type":"integer","description":"Reserved envelope, in whole pence."},"reservedEnvelopeDisplay":{"type":"string","description":"Reserved envelope, ready to show, such as £12.50."}},"required":["today","throughOn","budgetsEnabled","safeToSpend","points","movements","assumptions","missingData","startingCashMinor","startingCashDisplay","scheduledIncomeMinor","scheduledIncomeDisplay","scheduledExpenseMinor","scheduledExpenseDisplay","budgetUnscheduledMinor","budgetUnscheduledDisplay","goalCommitmentMinor","goalCommitmentDisplay","reservedGoalMinor","reservedGoalDisplay","reservedEnvelopeMinor","reservedEnvelopeDisplay"],"additionalProperties":false}}},"example":{"data":{"today":"2026-10-26","throughOn":"2026-11-25","budgetsEnabled":true,"startingCashMinor":184050,"startingCashDisplay":"£1,840.50","scheduledIncomeMinor":250000,"scheduledIncomeDisplay":"£2,500.00","scheduledExpenseMinor":-96200,"scheduledExpenseDisplay":"-£962.00","budgetUnscheduledMinor":-41500,"budgetUnscheduledDisplay":"-£415.00","goalCommitmentMinor":-20000,"goalCommitmentDisplay":"-£200.00","reservedGoalMinor":15000,"reservedGoalDisplay":"£150.00","reservedEnvelopeMinor":8000,"reservedEnvelopeDisplay":"£80.00","safeToSpend":{"throughOn":"2026-11-25","postedCashAccounts":[{"id":"acc_1","name":"Everyday account","amountMinor":184050,"amountDisplay":"£1,840.50"}],"keptAsideAccounts":[{"id":"acc_2","name":"Holiday pot","amountMinor":60000,"amountDisplay":"£600.00"}],"startingCashMinor":244050,"startingCashDisplay":"£2,440.50","excludedFutureIncomeMinor":0,"excludedFutureIncomeDisplay":"£0.00","scheduledIncomeMinor":0,"scheduledIncomeDisplay":"£0.00","scheduledExpenseMinor":96200,"scheduledExpenseDisplay":"£962.00","reservedGoalMinor":15000,"reservedGoalDisplay":"£150.00","reservedEnvelopeMinor":8000,"reservedEnvelopeDisplay":"£80.00","envelopeReleaseMinor":0,"envelopeReleaseDisplay":"£0.00","unreservedCashMinor":124850,"unreservedCashDisplay":"£1,248.50","keptAsideTotalMinor":60000,"keptAsideTotalDisplay":"£600.00","unusedCreditMinor":150000,"unusedCreditDisplay":"£1,500.00","amountMinor":124850,"amountDisplay":"£1,248.50","shortfallMinor":0,"shortfallDisplay":"£0.00"},"points":[{"date":"2026-11-02","movementIds":["mov_1"],"scheduledBalanceMinor":150750,"scheduledBalanceDisplay":"£1,507.50","upperAvailableMinor":150750,"upperAvailableDisplay":"£1,507.50","lowerAvailableMinor":130750,"lowerAvailableDisplay":"£1,307.50","scheduledIncomeMinor":0,"scheduledIncomeDisplay":"£0.00","scheduledExpenseMinor":-3299,"scheduledExpenseDisplay":"-£32.99","unscheduledBudgetMinor":-20000,"unscheduledBudgetDisplay":"-£200.00","goalCommitmentMinor":0,"goalCommitmentDisplay":"£0.00","envelopeReleaseMinor":0,"envelopeReleaseDisplay":"£0.00"}],"movements":[{"id":"mov_1","date":"2026-11-02","kind":"schedule","scheduleKind":"recurring","label":"Broadband","amountMinor":-3299,"amountDisplay":"-£32.99"}],"assumptions":["Scheduled items happen on their due day."],"missingData":[]}}}}},"400":{"description":"`validation_failed`: `days` is not 7, 14, 30, 60, 90 or 180. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/insights/runway":{"get":{"operationId":"getInsightsRunway","tags":["insights"],"summary":"Cash runway","description":"The dashboard's cash runway card: spendable cash today (credit cards and Keep aside accounts left out), what is coming in and out over the next 7, 30 and 90 days, and how many days of cover there are before cash first runs out (`runwayDays` is null when it never does). Overdue items count against the balance from today.\n\nNeeds the `insights:read` scope.","x-required-scope":"insights:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"today":{"type":"string","description":"A UK calendar day, YYYY-MM-DD."},"runwayDays":{"description":"Whole days of cover before cash first runs out; null if it never does in the next 90 days.","type":["integer","null"]},"firstNegativeOn":{"anyOf":[{"type":"string","description":"A UK calendar day, YYYY-MM-DD."},{"type":"null"}],"description":"The first day cash is projected to go below zero; null if it does not."},"liquidityRunwayDays":{"description":"The same, counting unused credit.","type":["integer","null"]},"creditUtilisationPercent":{"description":"How much of the credit limit is used, as a percentage; null with no credit.","type":["number","null"]},"workingDayShiftedCount":{"type":"integer","description":"How many payments were moved to the next working day."},"overdue":{"type":"object","properties":{"itemCount":{"type":"integer","description":"How many bills and payments it covers."},"inflowMinor":{"type":"integer","description":"Money coming in, in whole pence."},"inflowDisplay":{"type":"string","description":"Money coming in, ready to show, such as £12.50."},"outflowMinor":{"type":"integer","description":"Money going out, in whole pence."},"outflowDisplay":{"type":"string","description":"Money going out, ready to show, such as £12.50."},"netMinor":{"type":"integer","description":"Inflow minus outflow, in whole pence."},"netDisplay":{"type":"string","description":"Inflow minus outflow, ready to show, such as £12.50."}},"required":["itemCount","inflowMinor","inflowDisplay","outflowMinor","outflowDisplay","netMinor","netDisplay"],"description":"Cash already past the day it was due to move. Items that do not change planning cash are left out.","additionalProperties":false},"horizons":{"type":"array","items":{"type":"object","properties":{"days":{"type":"integer","description":"How many days ahead this horizon looks."},"endsOn":{"type":"string","description":"The last day of the horizon."},"status":{"type":"string","enum":["covered","tight","short"],"description":"Whether cash covers everything due in the horizon."},"itemCount":{"type":"integer","description":"How many bills and payments it covers."},"inflowMinor":{"type":"integer","description":"Money coming in, in whole pence."},"inflowDisplay":{"type":"string","description":"Money coming in, ready to show, such as £12.50."},"outflowMinor":{"type":"integer","description":"Money going out, in whole pence."},"outflowDisplay":{"type":"string","description":"Money going out, ready to show, such as £12.50."},"netMinor":{"type":"integer","description":"Inflow minus outflow, in whole pence."},"netDisplay":{"type":"string","description":"Inflow minus outflow, ready to show, such as £12.50."},"projectedBalanceMinor":{"type":"integer","description":"Projected cash at the end of the horizon, in whole pence."},"projectedBalanceDisplay":{"type":"string","description":"Projected cash at the end of the horizon, ready to show, such as £12.50."},"shortfallMinor":{"type":"integer","description":"How much is missing if cash does not cover everything due, in whole pence."},"shortfallDisplay":{"type":"string","description":"How much is missing if cash does not cover everything due, ready to show, such as £12.50."}},"required":["days","endsOn","status","itemCount","inflowMinor","inflowDisplay","outflowMinor","outflowDisplay","netMinor","netDisplay","projectedBalanceMinor","projectedBalanceDisplay","shortfallMinor","shortfallDisplay"],"additionalProperties":false},"description":"Cover for the next week, fortnight, month and so on."},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"The day."},"itemCount":{"type":"integer","description":"How many bills and payments fall on it."},"balanceMinor":{"type":"integer","description":"Projected cash at the end of the day, in whole pence."},"balanceDisplay":{"type":"string","description":"Projected cash at the end of the day, ready to show, such as £12.50."},"inflowMinor":{"type":"integer","description":"Money coming in that day, in whole pence."},"inflowDisplay":{"type":"string","description":"Money coming in that day, ready to show, such as £12.50."},"outflowMinor":{"type":"integer","description":"Money going out that day, in whole pence."},"outflowDisplay":{"type":"string","description":"Money going out that day, ready to show, such as £12.50."}},"required":["date","itemCount","balanceMinor","balanceDisplay","inflowMinor","inflowDisplay","outflowMinor","outflowDisplay"],"additionalProperties":false},"description":"Projected cash for each of the next 90 days."},"keptAsideAccounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The account id."},"name":{"type":"string","description":"The account name."},"amountMinor":{"type":"integer","description":"The account balance, in whole pence."},"amountDisplay":{"type":"string","description":"The account balance, ready to show, such as £12.50."}},"required":["id","name","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Accounts kept aside, left out of the figures."},"availableBalanceMinor":{"type":"integer","description":"Available balance, in whole pence."},"availableBalanceDisplay":{"type":"string","description":"Available balance, ready to show, such as £12.50."},"creditCardBalanceMinor":{"type":"integer","description":"Credit card balance, in whole pence."},"creditCardBalanceDisplay":{"type":"string","description":"Credit card balance, ready to show, such as £12.50."},"unusedCreditMinor":{"type":"integer","description":"Unused credit, in whole pence."},"unusedCreditDisplay":{"type":"string","description":"Unused credit, ready to show, such as £12.50."},"emergencyLiquidityMinor":{"type":"integer","description":"Emergency liquidity, in whole pence."},"emergencyLiquidityDisplay":{"type":"string","description":"Emergency liquidity, ready to show, such as £12.50."},"creditLimitMinor":{"type":"integer","description":"Credit limit, in whole pence."},"creditLimitDisplay":{"type":"string","description":"Credit limit, ready to show, such as £12.50."},"creditDebtMinor":{"type":"integer","description":"Credit debt, in whole pence."},"creditDebtDisplay":{"type":"string","description":"Credit debt, ready to show, such as £12.50."},"keptAsideTotalMinor":{"type":"integer","description":"Kept aside total, in whole pence."},"keptAsideTotalDisplay":{"type":"string","description":"Kept aside total, ready to show, such as £12.50."}},"required":["today","runwayDays","firstNegativeOn","liquidityRunwayDays","creditUtilisationPercent","workingDayShiftedCount","overdue","horizons","daily","keptAsideAccounts","availableBalanceMinor","availableBalanceDisplay","creditCardBalanceMinor","creditCardBalanceDisplay","unusedCreditMinor","unusedCreditDisplay","emergencyLiquidityMinor","emergencyLiquidityDisplay","creditLimitMinor","creditLimitDisplay","creditDebtMinor","creditDebtDisplay","keptAsideTotalMinor","keptAsideTotalDisplay"],"additionalProperties":false}}},"example":{"data":{"today":"2026-10-26","runwayDays":null,"firstNegativeOn":null,"liquidityRunwayDays":null,"creditUtilisationPercent":12.5,"workingDayShiftedCount":0,"availableBalanceMinor":184050,"availableBalanceDisplay":"£1,840.50","creditCardBalanceMinor":-18750,"creditCardBalanceDisplay":"-£187.50","unusedCreditMinor":131250,"unusedCreditDisplay":"£1,312.50","emergencyLiquidityMinor":315300,"emergencyLiquidityDisplay":"£3,153.00","creditLimitMinor":150000,"creditLimitDisplay":"£1,500.00","creditDebtMinor":18750,"creditDebtDisplay":"£187.50","keptAsideTotalMinor":60000,"keptAsideTotalDisplay":"£600.00","overdue":{"itemCount":0,"inflowMinor":0,"inflowDisplay":"£0.00","outflowMinor":0,"outflowDisplay":"£0.00","netMinor":0,"netDisplay":"£0.00"},"horizons":[{"days":7,"endsOn":"2026-11-02","status":"covered","itemCount":1,"inflowMinor":0,"inflowDisplay":"£0.00","outflowMinor":3299,"outflowDisplay":"£32.99","netMinor":-3299,"netDisplay":"-£32.99","projectedBalanceMinor":180751,"projectedBalanceDisplay":"£1,807.51","shortfallMinor":0,"shortfallDisplay":"£0.00"}],"daily":[{"date":"2026-11-02","itemCount":1,"balanceMinor":180751,"balanceDisplay":"£1,807.51","inflowMinor":0,"inflowDisplay":"£0.00","outflowMinor":3299,"outflowDisplay":"£32.99"}],"keptAsideAccounts":[{"id":"acc_2","name":"Holiday pot","amountMinor":60000,"amountDisplay":"£600.00"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/summaries":{"get":{"operationId":"getSummaries","tags":["insights"],"summary":"Period summaries","description":"The summaries library: one row per period that has a saved summary, newest first. The `id` is the latest saved version of that period; open it at `/summaries/{id}`.\n\nNeeds the `insights:read` scope.","x-required-scope":"insights:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"type","in":"query","required":false,"description":"The kind of period: weekly, biweekly, fourweekly, monthly, quarterly or annual. Default monthly.","schema":{"default":"monthly","type":"string","enum":["weekly","monthly","quarterly","annual","biweekly","fourweekly"]},"example":"monthly"},{"name":"limit","in":"query","required":false,"description":"Rows per page, 1 to 200.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The id of the latest saved version of this period."},"type":{"type":"string","enum":["weekly","biweekly","fourweekly","monthly","quarterly","annual"],"description":"The length of the period."},"periodKey":{"type":"string","description":"For example `2026-10` or `2026-W41`."},"periodStart":{"type":"string","description":"The first day of the period."},"periodEnd":{"type":"string","description":"The last day of the period."},"partial":{"type":"boolean","description":"The version was written while the period was still open."},"version":{"type":"integer","description":"Which saved version of the period this is; 1 is the first."},"versionCount":{"type":"integer","description":"How many versions of the period are saved."},"headline":{"description":"A one-line summary of the period.","type":["string","null"]},"transactionCount":{"description":"How many transactions the period holds.","type":["integer","null"]},"createdAt":{"description":"When this version was written, ISO 8601 in UTC.","type":["string","null"]},"incomeMinor":{"description":"Income, in whole pence; null when there is none.","type":["integer","null"]},"incomeDisplay":{"description":"Income, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"spendingMinor":{"description":"Spending, in whole pence; null when there is none.","type":["integer","null"]},"spendingDisplay":{"description":"Spending, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"netMinor":{"description":"Net, in whole pence; null when there is none.","type":["integer","null"]},"netDisplay":{"description":"Net, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"netChangeFromPriorMinor":{"description":"Net change from prior, in whole pence; null when there is none.","type":["integer","null"]},"netChangeFromPriorDisplay":{"description":"Net change from prior, ready to show, such as £12.50; null when there is none.","type":["string","null"]}},"required":["id","type","periodKey","periodStart","periodEnd","partial","version","versionCount","headline","transactionCount","createdAt","incomeMinor","incomeDisplay","spendingMinor","spendingDisplay","netMinor","netDisplay","netChangeFromPriorMinor","netChangeFromPriorDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"sum_1","type":"monthly","periodKey":"2026-09","periodStart":"2026-09-01","periodEnd":"2026-09-30","partial":false,"version":2,"versionCount":2,"headline":"You spent £1,874.50 and saved £1,325.50.","transactionCount":64,"createdAt":"2026-10-01T06:00:00.000Z","incomeMinor":320000,"incomeDisplay":"£3,200.00","spendingMinor":187450,"spendingDisplay":"£1,874.50","netMinor":132550,"netDisplay":"£1,325.50","netChangeFromPriorMinor":12300,"netChangeFromPriorDisplay":"£123.00"}],"page":{"nextCursor":null,"hasMore":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/summaries/{id}":{"get":{"operationId":"getSummariesById","tags":["insights"],"summary":"One period summary","description":"A saved summary version: totals, the written narrative, top categories and accounts, the daily series and anything unusual. `stale` says transactions in the period have changed since it was written; `versions` lists every saved version of the period. Some of it comes from other areas, so a key needs their scopes to see it: `topAccounts` is null without `accounts:read`, and an anomaly's `transactionId` is null without `transactions:read`, as is the `message` of one that names a transaction (the large-expense kind).\n\nNeeds the `insights:read` scope.","x-required-scope":"insights:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"A summary version id from `/summaries`.","schema":{"type":"string","minLength":1},"example":"sum_1"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The id of the latest saved version of this period."},"type":{"type":"string","enum":["weekly","biweekly","fourweekly","monthly","quarterly","annual"],"description":"The length of the period."},"periodKey":{"type":"string","description":"For example `2026-10` or `2026-W41`."},"periodStart":{"type":"string","description":"The first day of the period."},"periodEnd":{"type":"string","description":"The last day of the period."},"partial":{"type":"boolean","description":"The version was written while the period was still open."},"version":{"type":"integer","description":"Which saved version of the period this is; 1 is the first."},"versionCount":{"type":"integer","description":"How many versions of the period are saved."},"headline":{"description":"A one-line summary of the period.","type":["string","null"]},"transactionCount":{"description":"How many transactions the period holds.","type":["integer","null"]},"incomeMinor":{"description":"Income, in whole pence; null when there is none.","type":["integer","null"]},"incomeDisplay":{"description":"Income, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"spendingMinor":{"description":"Spending, in whole pence; null when there is none.","type":["integer","null"]},"spendingDisplay":{"description":"Spending, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"netMinor":{"description":"Net, in whole pence; null when there is none.","type":["integer","null"]},"netDisplay":{"description":"Net, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"netChangeFromPriorMinor":{"description":"Net change from prior, in whole pence; null when there is none.","type":["integer","null"]},"netChangeFromPriorDisplay":{"description":"Net change from prior, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"createdAt":{"description":"When this version was written, ISO 8601 in UTC.","type":["string","null"]},"stale":{"type":"boolean","description":"Transactions have changed since this version was written."},"narrative":{"type":"array","items":{"type":"string"},"description":"The summary written out as short paragraphs."},"topCategories":{"type":"array","items":{"type":"object","properties":{"categoryId":{"description":"The category id; null for uncategorised spending.","type":["string","null"]},"name":{"type":"string","description":"The category name."},"transactionCount":{"type":"integer","description":"How many transactions it holds."},"amountMinor":{"type":"integer","description":"Total spent in the category, in whole pence."},"amountDisplay":{"type":"string","description":"Total spent in the category, ready to show, such as £12.50."}},"required":["categoryId","name","transactionCount","amountMinor","amountDisplay"],"additionalProperties":false},"description":"The categories with the most spending."},"dailySeries":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"The day."},"transactionCount":{"type":"integer","description":"How many transactions it holds."},"incomeMinor":{"type":"integer","description":"Income, in whole pence."},"incomeDisplay":{"type":"string","description":"Income, ready to show, such as £12.50."},"spendingMinor":{"type":"integer","description":"Spending, in whole pence."},"spendingDisplay":{"type":"string","description":"Spending, ready to show, such as £12.50."},"netMinor":{"type":"integer","description":"Net, in whole pence."},"netDisplay":{"type":"string","description":"Net, ready to show, such as £12.50."},"balanceMinor":{"type":"integer","description":"Balance, in whole pence."},"balanceDisplay":{"type":"string","description":"Balance, ready to show, such as £12.50."}},"required":["date","transactionCount","incomeMinor","incomeDisplay","spendingMinor","spendingDisplay","netMinor","netDisplay","balanceMinor","balanceDisplay"],"additionalProperties":false}},{"type":"null"}],"description":"Day by day figures; null for older versions without them."},"topAccounts":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"The account id.","type":["string","null"]},"name":{"type":"string","description":"The account name."},"transactionCount":{"type":"integer","description":"How many transactions it holds."},"incomeMinor":{"type":"integer","description":"Income, in whole pence."},"incomeDisplay":{"type":"string","description":"Income, ready to show, such as £12.50."},"spendingMinor":{"type":"integer","description":"Spending, in whole pence."},"spendingDisplay":{"type":"string","description":"Spending, ready to show, such as £12.50."}},"required":["id","name","transactionCount","incomeMinor","incomeDisplay","spendingMinor","spendingDisplay"],"additionalProperties":false}},{"type":"null"}],"description":"Null for a key that cannot read accounts, and for older versions without it."},"anomalies":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"What kind of oddity it is, such as a large expense."},"message":{"description":"Null for a large expense when the key cannot read transactions: the text names it.","type":["string","null"]},"transactionId":{"description":"Null unless the key can read transactions.","type":["string","null"]},"amountMinor":{"description":"The amount involved, in whole pence; null when there is none.","type":["integer","null"]},"amountDisplay":{"description":"The amount involved, ready to show, such as £12.50; null when there is none.","type":["string","null"]}},"required":["kind","message","transactionId","amountMinor","amountDisplay"],"additionalProperties":false},"description":"Things that looked unusual in the period."},"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The version id."},"version":{"type":"integer","description":"The version number."},"partial":{"type":"boolean","description":"Written while the period was still open."},"createdAt":{"description":"When it was written, ISO 8601 in UTC.","type":["string","null"]}},"required":["id","version","partial","createdAt"],"additionalProperties":false},"description":"Every saved version of the period, newest first."},"openingBalanceMinor":{"description":"Opening balance, in whole pence; null when there is none.","type":["integer","null"]},"openingBalanceDisplay":{"description":"Opening balance, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"closingBalanceMinor":{"description":"Closing balance, in whole pence; null when there is none.","type":["integer","null"]},"closingBalanceDisplay":{"description":"Closing balance, ready to show, such as £12.50; null when there is none.","type":["string","null"]}},"required":["id","type","periodKey","periodStart","periodEnd","partial","version","versionCount","headline","transactionCount","incomeMinor","incomeDisplay","spendingMinor","spendingDisplay","netMinor","netDisplay","netChangeFromPriorMinor","netChangeFromPriorDisplay","createdAt","stale","narrative","topCategories","dailySeries","topAccounts","anomalies","versions","openingBalanceMinor","openingBalanceDisplay","closingBalanceMinor","closingBalanceDisplay"],"additionalProperties":false}}},"example":{"data":{"id":"sum_1","type":"monthly","periodKey":"2026-09","periodStart":"2026-09-01","periodEnd":"2026-09-30","partial":false,"version":2,"versionCount":2,"headline":"You spent £1,874.50 and saved £1,325.50.","transactionCount":64,"createdAt":"2026-10-01T06:00:00.000Z","incomeMinor":320000,"incomeDisplay":"£3,200.00","spendingMinor":187450,"spendingDisplay":"£1,874.50","netMinor":132550,"netDisplay":"£1,325.50","netChangeFromPriorMinor":12300,"netChangeFromPriorDisplay":"£123.00","stale":false,"narrative":["Groceries were your biggest category at £312.50."],"topCategories":[{"categoryId":"cat_groceries","name":"Groceries","transactionCount":14,"amountMinor":-31250,"amountDisplay":"-£312.50"}],"dailySeries":[{"date":"2026-09-01","transactionCount":3,"incomeMinor":0,"incomeDisplay":"£0.00","spendingMinor":4250,"spendingDisplay":"£42.50","netMinor":-4250,"netDisplay":"-£42.50","balanceMinor":179800,"balanceDisplay":"£1,798.00"}],"topAccounts":[{"id":"acc_1","name":"Everyday account","transactionCount":52,"incomeMinor":320000,"incomeDisplay":"£3,200.00","spendingMinor":187450,"spendingDisplay":"£1,874.50"}],"anomalies":[{"kind":"large_expense","message":"Car service was £189.00, more than usual.","transactionId":"txn_1","amountMinor":18900,"amountDisplay":"£189.00"}],"versions":[{"id":"sum_1","version":2,"partial":false,"createdAt":"2026-10-01T06:00:00.000Z"},{"id":"sum_0","version":1,"partial":true,"createdAt":"2026-09-30T06:00:00.000Z"}],"openingBalanceMinor":184000,"openingBalanceDisplay":"£1,840.00","closingBalanceMinor":316550,"closingBalanceDisplay":"£3,165.50"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents":{"get":{"operationId":"getDocuments","tags":["documents"],"summary":"List documents","description":"Your documents, newest first (by the date each is filed under). Pass `tab=trash` to see the Trash. `linkCount` counts only the attachments to areas the key can read (transactions, inbox items, accounts); the `linked` filter and the `unfiled` tab look at all attachments. To keep a copy in step, send `updatedSince`: only documents changed since then come back, trashed ones included and flagged. Answers 404 while documents are switched off for the whole app. A connected app gets only the payslips it may read, by pay date for `from` and `to`, and `linkCount` counts only what it can see; its pages can come back short, so follow `page.nextCursor` until it is null.\n\nNeeds the `documents:read` scope.","x-required-scope":"documents:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"tab","in":"query","required":false,"description":"`all` (default), `unfiled` (attached to nothing), `review` (waiting in the Documents inbox) or `trash`. With `updatedSince` and no tab, the Trash is included.","schema":{"type":"string","enum":["all","unfiled","review","trash"]},"example":"unfiled"},{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check). A document counts as changed on an edit, a link, or a step in its reading. A trashed document comes back with `trashedAt` set; once the Trash is emptied it is gone for good.","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"Only these kinds, comma-separated: `receipt,invoice`. `unknown` is a document with no kind set.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"example":"receipt"},{"name":"source","in":"query","required":false,"description":"Only documents that arrived this way: `upload`, `shortcut`, `share_target`, `email` or `system`.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"linked","in":"query","required":false,"description":"`true` for documents attached to anything (a transaction, an inbox item or an account, whatever the key can read), `false` for those attached to nothing.","schema":{"type":"string","enum":["0","1","true","false"]}},{"name":"from","in":"query","required":false,"description":"First day (`YYYY-MM-DD`) of the date a document is filed under, inclusive.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Last day (`YYYY-MM-DD`) of the date a document is filed under, inclusive.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Words to find in titles, file names, notes and the text read from the pages. Every word must match.","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"description":"Documents per page, 1 to 100. Default 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"example":"20"},{"name":"cursor","in":"query","required":false,"description":"`page.nextCursor` from the previous page.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name, else `Photo` or `PDF`."},"titleSource":{"anyOf":[{"type":"string","enum":["user","transaction"]},{"type":"null"}],"description":"What named it, when it was not the file."},"kind":{"type":"string","description":"`receipt`, `invoice`, `statement`, `payslip`, `tax`, `policy`, `warranty`, `letter`, `summary`, `other` or `unknown`."},"source":{"type":"string","enum":["upload","shortcut","share_target","email","system"],"description":"How it arrived."},"mimeType":{"type":"string","description":"The file type of the first file, such as `application/pdf`."},"family":{"type":"string","enum":["image","pdf"],"description":"Whether it is made of images or is a PDF."},"partCount":{"type":"integer","description":"Files that make it up: photos of a long receipt, say."},"pageCount":{"description":"How many pages it has, once known.","type":["integer","null"]},"sizeBytes":{"type":"integer","description":"All originals together, in bytes."},"processingStatus":{"type":"string","enum":["upload_pending","queued","processing","processed","needs_input","failed"],"description":"Where reading its text has got to: `processed` once done, `needs_input` when it waits for you, `failed` on an error."},"reviewStatus":{"type":"string","enum":["none","pending","done"],"description":"`pending` means it waits in the Documents inbox."},"linkCount":{"type":"integer","description":"Transactions, inbox items and accounts it is attached to. Only those the key can read are counted, as in `links`."},"pair":{"anyOf":[{"type":"object","properties":{"role":{"type":"string","enum":["lead","companion"],"description":"`lead`: the other files go with it (the receipt leads). `companion`: it goes with `leadId`."},"leadId":{"description":"For a companion, the document it goes with; null for a lead.","type":["string","null"]},"companionCount":{"type":"integer","description":"For a lead, how many other files are paired with it; 0 for a companion."},"state":{"type":"string","enum":["paired","suggested"],"description":"`paired`: attaching, detaching or filing one does them all. `suggested`: only offered, as “Same purchase as …?”."}},"required":["role","leadId","companionCount","state"],"additionalProperties":false},{"type":"null"}],"description":"The same purchase in other files, such as an invoice and its receipt from one email; null when it has none."},"date":{"description":"The day it is filed under, `YYYY-MM-DD`: the day it is dated when one is set (`documentDate`), else when it was taken, else when it arrived.","type":["string","null"]},"createdAt":{"description":"When it was added, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Changes whenever the document does."},"trashedAt":{"description":"Set while it is in the Trash.","type":["string","null"]},"purgeAfter":{"description":"When the Trash removes it for good.","type":["string","null"]},"snippet":{"description":"Where a search matched, as plain text.","type":["string","null"]}},"required":["id","title","titleSource","kind","source","mimeType","family","partCount","pageCount","sizeBytes","processingStatus","reviewStatus","linkCount","pair","date","createdAt","updatedAt","version","trashedAt","purgeAfter","snippet"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","title":"Boots receipt","titleSource":"user","kind":"receipt","source":"shortcut","mimeType":"image/jpeg","family":"image","partCount":1,"pageCount":1,"sizeBytes":184320,"processingStatus":"processed","reviewStatus":"none","linkCount":1,"pair":null,"date":"2026-10-20","createdAt":"2026-10-20T14:03:11.000Z","updatedAt":"2026-10-20T14:05:40.000Z","version":"1792505140000","trashedAt":null,"purgeAfter":null,"snippet":null}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"`unavailable`: The document vault is not answering.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postDocuments","tags":["documents"],"summary":"Upload a document in one request","description":"Adds a photo or PDF to your Documents inbox. Send a `multipart/form-data` form with the file in a field named `file` (several photos become the pages of one document) and, optionally, text read on the phone (Live Text) in `clientOcrText`. All files together can be at most 4 MB: for anything bigger, or a long receipt, use `POST /documents/uploads`. Answers 201 `added` with the new document’s id and the address that opens it in the app, or 200 `duplicate` when the same file is already a document (which document has it is never said). Counts against the key’s 200 upload calls per UK day (`rate_limited`, `reason: daily_limit`). A key with `documents:upload` or `documents:write` can use it. Send an `Idempotency-Key` to make a retry safe: the same key with the same file answers the first result again, the same key with another file is a 422.\n\nNeeds the `documents:upload` scope.","x-required-scope":"documents:upload","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["added","duplicate"],"description":"`added` for a new document, `duplicate` when the file was already there."},"documentId":{"description":"The new document. Not given for a duplicate.","type":"string"},"url":{"description":"Where the document opens in the app. Not given for a duplicate.","type":"string"}},"required":["status"],"additionalProperties":false}}},"example":{"data":{"status":"added","documentId":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","url":"https://finance.example.com/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/details"}}}}},"400":{"description":"`validation_failed`: The request is not a `multipart/form-data` form (`reason: not_multipart`) or has no `file` (`reason: no_file`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"description":"`payload_too_large`: The files together are over 4 MB (`reason: too_large`); use `POST /documents/uploads`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"description":"`rate_limited`: The key has used its 200 upload calls for the UK day (`reason: daily_limit`). The key has used up its rate limit; wait `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`unavailable`: Document storage is down or not set up; retry after the `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/search":{"get":{"operationId":"getDocumentsSearch","tags":["documents"],"summary":"Search documents by meaning","description":"Finds documents about what you describe, even when the words differ (\"car insurance renewal\" finds the policy letter). Closest first, and only documents within a sensible distance. Your words are sent to the DocIntel service to be turned into a vector; they are never kept. Answers 503 `unavailable` while search by meaning is switched off or DocIntel is down or waking (see `Retry-After`); use `GET /documents?q=` for a plain word search.\n\nNeeds the `documents:read` scope.","x-required-scope":"documents:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"What the document is about, in your own words. At least 3 characters.","schema":{"type":"string","minLength":1,"maxLength":2000},"example":"pharmacy receipt for vitamins"},{"name":"tab","in":"query","required":false,"description":"Which documents to search, as for `GET /documents`.","schema":{"default":"all","type":"string","enum":["all","unfiled","review","trash"]}},{"name":"limit","in":"query","required":false,"description":"Documents to return, 1 to 20. Default 10.","schema":{"default":10,"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name, else `Photo` or `PDF`."},"titleSource":{"anyOf":[{"type":"string","enum":["user","transaction"]},{"type":"null"}],"description":"What named it, when it was not the file."},"kind":{"type":"string","description":"`receipt`, `invoice`, `statement`, `payslip`, `tax`, `policy`, `warranty`, `letter`, `summary`, `other` or `unknown`."},"source":{"type":"string","enum":["upload","shortcut","share_target","email","system"],"description":"How it arrived."},"mimeType":{"type":"string","description":"The file type of the first file, such as `application/pdf`."},"family":{"type":"string","enum":["image","pdf"],"description":"Whether it is made of images or is a PDF."},"partCount":{"type":"integer","description":"Files that make it up: photos of a long receipt, say."},"pageCount":{"description":"How many pages it has, once known.","type":["integer","null"]},"sizeBytes":{"type":"integer","description":"All originals together, in bytes."},"processingStatus":{"type":"string","enum":["upload_pending","queued","processing","processed","needs_input","failed"],"description":"Where reading its text has got to: `processed` once done, `needs_input` when it waits for you, `failed` on an error."},"reviewStatus":{"type":"string","enum":["none","pending","done"],"description":"`pending` means it waits in the Documents inbox."},"linkCount":{"type":"integer","description":"Transactions, inbox items and accounts it is attached to. Only those the key can read are counted, as in `links`."},"pair":{"anyOf":[{"type":"object","properties":{"role":{"type":"string","enum":["lead","companion"],"description":"`lead`: the other files go with it (the receipt leads). `companion`: it goes with `leadId`."},"leadId":{"description":"For a companion, the document it goes with; null for a lead.","type":["string","null"]},"companionCount":{"type":"integer","description":"For a lead, how many other files are paired with it; 0 for a companion."},"state":{"type":"string","enum":["paired","suggested"],"description":"`paired`: attaching, detaching or filing one does them all. `suggested`: only offered, as “Same purchase as …?”."}},"required":["role","leadId","companionCount","state"],"additionalProperties":false},{"type":"null"}],"description":"The same purchase in other files, such as an invoice and its receipt from one email; null when it has none."},"date":{"description":"The day it is filed under, `YYYY-MM-DD`: the day it is dated when one is set (`documentDate`), else when it was taken, else when it arrived.","type":["string","null"]},"createdAt":{"description":"When it was added, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Changes whenever the document does."},"trashedAt":{"description":"Set while it is in the Trash.","type":["string","null"]},"purgeAfter":{"description":"When the Trash removes it for good.","type":["string","null"]},"snippet":{"description":"Where a search matched, as plain text.","type":["string","null"]},"match":{"type":"object","properties":{"distance":{"type":"number","description":"How far the closest passage is from the search, 0 to 0.7. Smaller is closer."},"closeness":{"type":"string","enum":["very_close","close","related"],"description":"The distance in words."},"page":{"type":"integer","description":"The page that passage is on."}},"required":["distance","closeness","page"],"description":"How closely the document matches the search.","additionalProperties":false}},"required":["id","title","titleSource","kind","source","mimeType","family","partCount","pageCount","sizeBytes","processingStatus","reviewStatus","linkCount","pair","date","createdAt","updatedAt","version","trashedAt","purgeAfter","snippet","match"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","title":"Boots receipt","titleSource":"user","kind":"receipt","source":"shortcut","mimeType":"image/jpeg","family":"image","partCount":1,"pageCount":1,"sizeBytes":184320,"processingStatus":"processed","reviewStatus":"none","linkCount":1,"pair":null,"date":"2026-10-20","createdAt":"2026-10-20T14:03:11.000Z","updatedAt":"2026-10-20T14:05:40.000Z","version":"1792505140000","trashedAt":null,"purgeAfter":null,"snippet":"Boots Pharmacy, Vitamin D 90 tablets …","match":{"distance":0.512,"closeness":"close","page":1}}],"page":{"nextCursor":null,"hasMore":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"`unavailable`: Search by meaning is switched off, or DocIntel is down or waking; retry after `Retry-After`, or use `GET /documents?q=`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}":{"get":{"operationId":"getDocumentsById","tags":["documents"],"summary":"Get a document","description":"One document, including one in the Trash. `links` lists what it is attached to; a link to a transaction, inbox item or account is only shown when the key can also read that area. `reading` holds the headline values Read with AI found, if it has been read that way, and for a payslip `reading.payslip` has its pay, deductions and year-to-date figures (never the National Insurance number). `lines` lists the lines it read, each with the transaction line it is on when the key can also read transactions.\n\nNeeds the `documents:read` scope.","x-required-scope":"documents:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_3b8e5d2a-7c41-4f6a-9e0d-2a1b4c6d8e0f"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name, else `Photo` or `PDF`."},"titleSource":{"anyOf":[{"type":"string","enum":["user","transaction"]},{"type":"null"}],"description":"What named it, when it was not the file."},"kind":{"type":"string","description":"`receipt`, `invoice`, `statement`, `payslip`, `tax`, `policy`, `warranty`, `letter`, `summary`, `other` or `unknown`."},"source":{"type":"string","enum":["upload","shortcut","share_target","email","system"],"description":"How it arrived."},"mimeType":{"type":"string","description":"The file type of the first file, such as `application/pdf`."},"family":{"type":"string","enum":["image","pdf"],"description":"Whether it is made of images or is a PDF."},"partCount":{"type":"integer","description":"Files that make it up: photos of a long receipt, say."},"pageCount":{"description":"How many pages it has, once known.","type":["integer","null"]},"sizeBytes":{"type":"integer","description":"All originals together, in bytes."},"processingStatus":{"type":"string","enum":["upload_pending","queued","processing","processed","needs_input","failed"],"description":"Where reading its text has got to: `processed` once done, `needs_input` when it waits for you, `failed` on an error."},"reviewStatus":{"type":"string","enum":["none","pending","done"],"description":"`pending` means it waits in the Documents inbox."},"linkCount":{"type":"integer","description":"Transactions, inbox items and accounts it is attached to. Only those the key can read are counted, as in `links`."},"pair":{"anyOf":[{"type":"object","properties":{"role":{"type":"string","enum":["lead","companion"],"description":"`lead`: the other files go with it (the receipt leads). `companion`: it goes with `leadId`."},"leadId":{"description":"For a companion, the document it goes with; null for a lead.","type":["string","null"]},"companionCount":{"type":"integer","description":"For a lead, how many other files are paired with it; 0 for a companion."},"state":{"type":"string","enum":["paired","suggested"],"description":"`paired`: attaching, detaching or filing one does them all. `suggested`: only offered, as “Same purchase as …?”."}},"required":["role","leadId","companionCount","state"],"additionalProperties":false},{"type":"null"}],"description":"The same purchase in other files, such as an invoice and its receipt from one email; null when it has none."},"date":{"description":"The day it is filed under, `YYYY-MM-DD`: the day it is dated when one is set (`documentDate`), else when it was taken, else when it arrived.","type":["string","null"]},"createdAt":{"description":"When it was added, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Changes whenever the document does."},"trashedAt":{"description":"Set while it is in the Trash.","type":["string","null"]},"purgeAfter":{"description":"When the Trash removes it for good.","type":["string","null"]},"snippet":{"description":"Where a search matched, as plain text.","type":["string","null"]},"originalFilename":{"description":"The name of the first file as it was uploaded.","type":["string","null"]},"notes":{"description":"Free-text notes.","type":["string","null"]},"documentDate":{"description":"The day it is dated, `YYYY-MM-DD`, when you or a suggested date you used set one; null when none is set.","type":["string","null"]},"documentTime":{"description":"The time of that day it is dated, `HH:MM` on the UK clock (Europe/London), when one is set with `documentDate` (a receipt’s printed time, say); null when none is. Documents on the same day are listed by it.","type":["string","null"]},"paidDate":{"description":"The day it was paid, `YYYY-MM-DD`: its transaction’s day when it’s attached to one (the latest, if several), else a day you set; null when not known. Shown only: `date` is what it’s filed under.","type":["string","null"]},"paidFrom":{"anyOf":[{"type":"string","enum":["transaction","you"]},{"type":"null"}],"description":"Where `paidDate` comes from: its transaction, or you."},"capturedAt":{"description":"When the photo or scan was taken, ISO 8601 in UTC, when known.","type":["string","null"]},"processingError":{"description":"Why reading it failed, when `processingStatus` is `failed`.","type":["string","null"]},"links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The link, starts with `dln_`."},"targetType":{"type":"string","enum":["transaction","inbox_item","account"],"description":"What kind of thing it is attached to."},"targetId":{"type":"string","description":"The transaction, inbox item or account it is attached to."},"linkSource":{"anyOf":[{"type":"string","enum":["user","auto_match","system"]},{"type":"null"}],"description":"Who attached it. Not given for accounts."},"periodStart":{"description":"Accounts only: the statement period, first day.","type":["string","null"]},"periodEnd":{"description":"Accounts only: the statement period, last day.","type":["string","null"]}},"required":["id","targetType","targetId","linkSource","periodStart","periodEnd"],"additionalProperties":false},"description":"What it is attached to. Only things the key can read are listed."},"pairMembers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name."},"role":{"type":"string","enum":["lead","companion"],"description":"`lead`: the one the pair goes by (the receipt)."}},"required":["id","title","role"],"additionalProperties":false},"description":"The rest of its pair, the lead first; empty when it is not paired."},"suggestedPair":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name."}},"required":["id","title"],"additionalProperties":false},{"type":"null"}],"description":"A document from somewhere else offered as the same purchase, not yet paired; null when none."},"reading":{"anyOf":[{"type":"object","properties":{"formKind":{"description":"What it was read as: `receipt`, `invoice`, …","type":["string","null"]},"readAt":{"description":"When it was read, ISO 8601 in UTC.","type":["string","null"]},"current":{"type":"boolean","description":"False when the document was read again since this reading."},"merchant":{"description":"The shop or company the reading found.","type":["string","null"]},"date":{"description":"`YYYY-MM-DD`, when the reading found a date.","type":["string","null"]},"totalMinor":{"description":"The total found, in whole pence; null when none.","type":["integer","null"]},"totalDisplay":{"description":"Ready to show, such as `£12.50`.","type":["string","null"]},"payslip":{"anyOf":[{"type":"object","properties":{"employer":{"description":"Who paid you, as the payslip names them.","type":["string","null"]},"payDate":{"description":"The day it says you were paid, `YYYY-MM-DD`.","type":["string","null"]},"payPeriod":{"description":"The period it pays for, as printed, such as `October 2026` or `Week 28`.","type":["string","null"]},"taxCode":{"description":"The tax code it was worked out with, such as `1257L`.","type":["string","null"]},"grossPayMinor":{"description":"Gross pay for the period, in whole pence; null when there is none.","type":["integer","null"]},"grossPayDisplay":{"description":"Gross pay for the period, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"incomeTaxMinor":{"description":"Income tax taken off, in whole pence; null when there is none.","type":["integer","null"]},"incomeTaxDisplay":{"description":"Income tax taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"nationalInsuranceMinor":{"description":"National Insurance taken off, in whole pence; null when there is none.","type":["integer","null"]},"nationalInsuranceDisplay":{"description":"National Insurance taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"pensionMinor":{"description":"Your pension contribution taken off, in whole pence; null when there is none.","type":["integer","null"]},"pensionDisplay":{"description":"Your pension contribution taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"studentLoanMinor":{"description":"Student loan repayment taken off, in whole pence; null when there is none.","type":["integer","null"]},"studentLoanDisplay":{"description":"Student loan repayment taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"otherDeductionsMinor":{"description":"Whatever its total deductions take besides the four above (a share scheme, a union), 0 when they are all of it, in whole pence; null when there is none.","type":["integer","null"]},"otherDeductionsDisplay":{"description":"Whatever its total deductions take besides the four above (a share scheme, a union), 0 when they are all of it, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"netPayMinor":{"description":"Net pay: what it says reached your bank, in whole pence; null when there is none.","type":["integer","null"]},"netPayDisplay":{"description":"Net pay: what it says reached your bank, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"yearToDate":{"type":"object","properties":{"grossPayMinor":{"description":"Gross pay in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"grossPayDisplay":{"description":"Gross pay in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"incomeTaxMinor":{"description":"Income tax in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"incomeTaxDisplay":{"description":"Income tax in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"nationalInsuranceMinor":{"description":"National Insurance in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"nationalInsuranceDisplay":{"description":"National Insurance in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"pensionMinor":{"description":"Pension contributions in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"pensionDisplay":{"description":"Pension contributions in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]}},"required":["grossPayMinor","grossPayDisplay","incomeTaxMinor","incomeTaxDisplay","nationalInsuranceMinor","nationalInsuranceDisplay","pensionMinor","pensionDisplay"],"description":"The tax year so far, as the payslip prints it.","additionalProperties":false}},"required":["employer","payDate","payPeriod","taxCode","grossPayMinor","grossPayDisplay","incomeTaxMinor","incomeTaxDisplay","nationalInsuranceMinor","nationalInsuranceDisplay","pensionMinor","pensionDisplay","studentLoanMinor","studentLoanDisplay","otherDeductionsMinor","otherDeductionsDisplay","netPayMinor","netPayDisplay","yearToDate"],"additionalProperties":false},{"type":"null"}],"description":"For a document read as a payslip: what it says, from the same figures Itemise salary uses. Deductions are positive, the money taken off. A value dismissed in the app is null. Never the National Insurance number. Null for anything not read as a payslip."}},"required":["formKind","readAt","current","merchant","date","totalMinor","totalDisplay","payslip"],"additionalProperties":false},{"type":"null"}],"description":"The headline values Read with AI found; `null` until a document has been read that way."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line, starts with `dli_`. A new reading gives every line a new id."},"position":{"type":"integer","description":"Its place in the reading’s lines, from 0."},"description":{"description":"What the line says, such as `Gross pay`. Account and card numbers are masked.","type":["string","null"]},"kind":{"anyOf":[{"type":"string","enum":["item","discount","subtotal","tax","service","tip","total","payment","change","other"]},{"type":"null"}],"description":"What the line is, where the reading labelled it: `item` or `discount` on a receipt or invoice. Null where it did not, as on a payslip, whose gross pay is positive and each deduction negative."},"quantity":{"description":"How many, where the line printed it.","type":["number","null"]},"unitPriceMinor":{"description":"The price of one, where the line printed it, in whole pence; null when there is none.","type":["integer","null"]},"unitPriceDisplay":{"description":"The price of one, where the line printed it, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"amountMinor":{"description":"The line’s amount as printed: an item positive, a discount or deduction negative, in whole pence; null when there is none.","type":["integer","null"]},"amountDisplay":{"description":"The line’s amount as printed: an item positive, a discount or deduction negative, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"status":{"type":"string","enum":["verified","found_elsewhere","unsupported","disputed","missing"],"description":"How sure the reading is of it: `verified` when it was found where the reading says."},"ofPosition":{"description":"A discount printed under its item (a loyalty price): that item’s `position`; null otherwise.","type":["integer","null"]},"dismissed":{"type":"boolean","description":"True when you said it is fine for it to be missing from the transaction."},"transactionLine":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The transaction line it is on."},"transactionId":{"type":"string","description":"The transaction that line is part of."},"linkSource":{"type":"string","enum":["create","itemise","user","paired"],"description":"How it got there: made by Create or Itemise, linked by you, or a pairing you kept."}},"required":["id","transactionId","linkSource"],"additionalProperties":false},{"type":"null"}],"description":"The transaction line this line is on. Null when it is on none, or the key cannot read transactions."}},"required":["id","position","description","kind","quantity","unitPriceMinor","unitPriceDisplay","amountMinor","amountDisplay","status","ofPosition","dismissed","transactionLine"],"additionalProperties":false},"description":"The lines its reading found, in order: a receipt’s items and discounts, a payslip’s gross pay and deductions. Empty until it has been read with AI, or when its reading was dismissed."}},"required":["id","title","titleSource","kind","source","mimeType","family","partCount","pageCount","sizeBytes","processingStatus","reviewStatus","linkCount","pair","date","createdAt","updatedAt","version","trashedAt","purgeAfter","snippet","originalFilename","notes","documentDate","documentTime","paidDate","paidFrom","capturedAt","processingError","links","pairMembers","suggestedPair","reading","lines"],"additionalProperties":false}}},"example":{"data":{"id":"doc_3b8e5d2a-7c41-4f6a-9e0d-2a1b4c6d8e0f","title":"Payslip October 2026","titleSource":null,"kind":"payslip","source":"upload","mimeType":"application/pdf","family":"pdf","partCount":1,"pageCount":1,"sizeBytes":96512,"processingStatus":"processed","reviewStatus":"none","linkCount":1,"pair":null,"date":"2026-10-09","createdAt":"2026-10-09T07:40:12.000Z","updatedAt":"2026-10-09T07:44:30.000Z","version":"1791531870000","trashedAt":null,"purgeAfter":null,"snippet":null,"originalFilename":"Payslip-2026-10.pdf","notes":null,"documentDate":null,"documentTime":null,"paidDate":"2026-10-09","paidFrom":"transaction","capturedAt":null,"processingError":null,"links":[{"id":"dln_4d5e6f7a-8b9c-4d0e-a1f2-3b4c5d6e7f80","targetType":"transaction","targetId":"e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b","linkSource":"user","periodStart":null,"periodEnd":null}],"pairMembers":[],"suggestedPair":null,"reading":{"formKind":"payslip","readAt":"2026-10-09T07:43:05.000Z","current":true,"merchant":"Example Retail Ltd","date":"2026-10-09","totalMinor":108413,"totalDisplay":"£1,084.13","payslip":{"employer":"Example Retail Ltd","payDate":"2026-10-09","payPeriod":"Month 7","taxCode":"1257L","grossPayMinor":124125,"grossPayDisplay":"£1,241.25","incomeTaxMinor":4720,"incomeTaxDisplay":"£47.20","nationalInsuranceMinor":2186,"nationalInsuranceDisplay":"£21.86","pensionMinor":3806,"pensionDisplay":"£38.06","studentLoanMinor":null,"studentLoanDisplay":null,"otherDeductionsMinor":5000,"otherDeductionsDisplay":"£50.00","netPayMinor":108413,"netPayDisplay":"£1,084.13","yearToDate":{"grossPayMinor":868875,"grossPayDisplay":"£8,688.75","incomeTaxMinor":33040,"incomeTaxDisplay":"£330.40","nationalInsuranceMinor":15302,"nationalInsuranceDisplay":"£153.02","pensionMinor":26642,"pensionDisplay":"£266.42"}}},"lines":[{"id":"dli_7e4a2c9b-1d3f-4a5e-8b6c-0f1e2d3c4b50","position":0,"description":"Gross pay","kind":null,"quantity":null,"unitPriceMinor":null,"unitPriceDisplay":null,"amountMinor":124125,"amountDisplay":"£1,241.25","status":"verified","ofPosition":null,"dismissed":false,"transactionLine":{"id":"c9d0e1f2-a3b4-4c5d-8e6f-7a8b9c0d1e20","transactionId":"e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b","linkSource":"itemise"}},{"id":"dli_7e4a2c9b-1d3f-4a5e-8b6c-0f1e2d3c4b51","position":1,"description":"Income tax","kind":null,"quantity":null,"unitPriceMinor":null,"unitPriceDisplay":null,"amountMinor":-4720,"amountDisplay":"-£47.20","status":"verified","ofPosition":null,"dismissed":false,"transactionLine":{"id":"c9d0e1f2-a3b4-4c5d-8e6f-7a8b9c0d1e21","transactionId":"e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b","linkSource":"itemise"}},{"id":"dli_7e4a2c9b-1d3f-4a5e-8b6c-0f1e2d3c4b52","position":2,"description":"National Insurance","kind":null,"quantity":null,"unitPriceMinor":null,"unitPriceDisplay":null,"amountMinor":-2186,"amountDisplay":"-£21.86","status":"verified","ofPosition":null,"dismissed":false,"transactionLine":{"id":"c9d0e1f2-a3b4-4c5d-8e6f-7a8b9c0d1e22","transactionId":"e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b","linkSource":"itemise"}},{"id":"dli_7e4a2c9b-1d3f-4a5e-8b6c-0f1e2d3c4b53","position":3,"description":"Pension","kind":null,"quantity":null,"unitPriceMinor":null,"unitPriceDisplay":null,"amountMinor":-3806,"amountDisplay":"-£38.06","status":"verified","ofPosition":null,"dismissed":false,"transactionLine":{"id":"c9d0e1f2-a3b4-4c5d-8e6f-7a8b9c0d1e23","transactionId":"e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b","linkSource":"itemise"}},{"id":"dli_7e4a2c9b-1d3f-4a5e-8b6c-0f1e2d3c4b54","position":4,"description":"Other deductions","kind":null,"quantity":null,"unitPriceMinor":null,"unitPriceDisplay":null,"amountMinor":-5000,"amountDisplay":"-£50.00","status":"verified","ofPosition":null,"dismissed":false,"transactionLine":{"id":"c9d0e1f2-a3b4-4c5d-8e6f-7a8b9c0d1e24","transactionId":"e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b","linkSource":"itemise"}}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app, or the document does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"`unavailable`: The document vault is not answering.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchDocumentsById","tags":["documents"],"summary":"Change a document’s details","description":"Renames a document, changes its kind, notes or date, or files it without a transaction (`reviewed: true`) or sends it to the Documents inbox from anywhere in the vault (`reviewed: false`). Send only what changes. A title is your choice, so the app never renames the document afterwards; a blank title means the file’s name. A document in the Trash must be restored first. Send the `version` from the last read as `If-Match` (or in the body) to refuse the change if the document changed since (412 `version_conflict`). Answers with the document as `GET /documents/{id}` shows it.\n\nNeeds the `documents:write` scope.","x-required-scope":"documents:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"A new title, up to 200 characters. `null` or blank means the file’s name.","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"kind":{"description":"`receipt`, `invoice`, `statement`, `payslip`, `tax`, `policy`, `warranty`, `letter`, `summary`, `other` or `unknown` (not set).","type":"string","enum":["receipt","invoice","statement","payslip","tax","policy","warranty","letter","summary","other","unknown"]},"notes":{"description":"Your notes, up to 5000 characters. `null` or blank clears them.","anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"date":{"description":"The day it is dated, `YYYY-MM-DD`, from 2000 to tomorrow. `null` clears it (and its time), so it is filed under when it was taken or arrived again.","anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"time":{"description":"The time of that day it is dated, `HH:MM` on the UK clock (Europe/London); it needs a date, sent with it or already set. `null` clears it. Left out, it stays, unless `date` changes to another day.","anyOf":[{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},{"type":"null"}]},"paidDate":{"description":"The day it was paid, `YYYY-MM-DD`, for a document on no transaction (one on a transaction is paid that transaction’s day). `null` clears it.","anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"reviewed":{"description":"`true` files a document waiting in the Documents inbox without a transaction; `false` sends it to the Documents inbox, from anywhere in the vault. What it is attached to stays.","type":"boolean"},"version":{"description":"The `version` you last read; the same as sending `If-Match`.","type":"string","maxLength":40}},"additionalProperties":false},"example":{"title":"Boots vitamins","kind":"receipt","reviewed":true}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name, else `Photo` or `PDF`."},"titleSource":{"anyOf":[{"type":"string","enum":["user","transaction"]},{"type":"null"}],"description":"What named it, when it was not the file."},"kind":{"type":"string","description":"`receipt`, `invoice`, `statement`, `payslip`, `tax`, `policy`, `warranty`, `letter`, `summary`, `other` or `unknown`."},"source":{"type":"string","enum":["upload","shortcut","share_target","email","system"],"description":"How it arrived."},"mimeType":{"type":"string","description":"The file type of the first file, such as `application/pdf`."},"family":{"type":"string","enum":["image","pdf"],"description":"Whether it is made of images or is a PDF."},"partCount":{"type":"integer","description":"Files that make it up: photos of a long receipt, say."},"pageCount":{"description":"How many pages it has, once known.","type":["integer","null"]},"sizeBytes":{"type":"integer","description":"All originals together, in bytes."},"processingStatus":{"type":"string","enum":["upload_pending","queued","processing","processed","needs_input","failed"],"description":"Where reading its text has got to: `processed` once done, `needs_input` when it waits for you, `failed` on an error."},"reviewStatus":{"type":"string","enum":["none","pending","done"],"description":"`pending` means it waits in the Documents inbox."},"linkCount":{"type":"integer","description":"Transactions, inbox items and accounts it is attached to. Only those the key can read are counted, as in `links`."},"pair":{"anyOf":[{"type":"object","properties":{"role":{"type":"string","enum":["lead","companion"],"description":"`lead`: the other files go with it (the receipt leads). `companion`: it goes with `leadId`."},"leadId":{"description":"For a companion, the document it goes with; null for a lead.","type":["string","null"]},"companionCount":{"type":"integer","description":"For a lead, how many other files are paired with it; 0 for a companion."},"state":{"type":"string","enum":["paired","suggested"],"description":"`paired`: attaching, detaching or filing one does them all. `suggested`: only offered, as “Same purchase as …?”."}},"required":["role","leadId","companionCount","state"],"additionalProperties":false},{"type":"null"}],"description":"The same purchase in other files, such as an invoice and its receipt from one email; null when it has none."},"date":{"description":"The day it is filed under, `YYYY-MM-DD`: the day it is dated when one is set (`documentDate`), else when it was taken, else when it arrived.","type":["string","null"]},"createdAt":{"description":"When it was added, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Changes whenever the document does."},"trashedAt":{"description":"Set while it is in the Trash.","type":["string","null"]},"purgeAfter":{"description":"When the Trash removes it for good.","type":["string","null"]},"snippet":{"description":"Where a search matched, as plain text.","type":["string","null"]},"originalFilename":{"description":"The name of the first file as it was uploaded.","type":["string","null"]},"notes":{"description":"Free-text notes.","type":["string","null"]},"documentDate":{"description":"The day it is dated, `YYYY-MM-DD`, when you or a suggested date you used set one; null when none is set.","type":["string","null"]},"documentTime":{"description":"The time of that day it is dated, `HH:MM` on the UK clock (Europe/London), when one is set with `documentDate` (a receipt’s printed time, say); null when none is. Documents on the same day are listed by it.","type":["string","null"]},"paidDate":{"description":"The day it was paid, `YYYY-MM-DD`: its transaction’s day when it’s attached to one (the latest, if several), else a day you set; null when not known. Shown only: `date` is what it’s filed under.","type":["string","null"]},"paidFrom":{"anyOf":[{"type":"string","enum":["transaction","you"]},{"type":"null"}],"description":"Where `paidDate` comes from: its transaction, or you."},"capturedAt":{"description":"When the photo or scan was taken, ISO 8601 in UTC, when known.","type":["string","null"]},"processingError":{"description":"Why reading it failed, when `processingStatus` is `failed`.","type":["string","null"]},"links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The link, starts with `dln_`."},"targetType":{"type":"string","enum":["transaction","inbox_item","account"],"description":"What kind of thing it is attached to."},"targetId":{"type":"string","description":"The transaction, inbox item or account it is attached to."},"linkSource":{"anyOf":[{"type":"string","enum":["user","auto_match","system"]},{"type":"null"}],"description":"Who attached it. Not given for accounts."},"periodStart":{"description":"Accounts only: the statement period, first day.","type":["string","null"]},"periodEnd":{"description":"Accounts only: the statement period, last day.","type":["string","null"]}},"required":["id","targetType","targetId","linkSource","periodStart","periodEnd"],"additionalProperties":false},"description":"What it is attached to. Only things the key can read are listed."},"pairMembers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name."},"role":{"type":"string","enum":["lead","companion"],"description":"`lead`: the one the pair goes by (the receipt)."}},"required":["id","title","role"],"additionalProperties":false},"description":"The rest of its pair, the lead first; empty when it is not paired."},"suggestedPair":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name."}},"required":["id","title"],"additionalProperties":false},{"type":"null"}],"description":"A document from somewhere else offered as the same purchase, not yet paired; null when none."},"reading":{"anyOf":[{"type":"object","properties":{"formKind":{"description":"What it was read as: `receipt`, `invoice`, …","type":["string","null"]},"readAt":{"description":"When it was read, ISO 8601 in UTC.","type":["string","null"]},"current":{"type":"boolean","description":"False when the document was read again since this reading."},"merchant":{"description":"The shop or company the reading found.","type":["string","null"]},"date":{"description":"`YYYY-MM-DD`, when the reading found a date.","type":["string","null"]},"totalMinor":{"description":"The total found, in whole pence; null when none.","type":["integer","null"]},"totalDisplay":{"description":"Ready to show, such as `£12.50`.","type":["string","null"]},"payslip":{"anyOf":[{"type":"object","properties":{"employer":{"description":"Who paid you, as the payslip names them.","type":["string","null"]},"payDate":{"description":"The day it says you were paid, `YYYY-MM-DD`.","type":["string","null"]},"payPeriod":{"description":"The period it pays for, as printed, such as `October 2026` or `Week 28`.","type":["string","null"]},"taxCode":{"description":"The tax code it was worked out with, such as `1257L`.","type":["string","null"]},"grossPayMinor":{"description":"Gross pay for the period, in whole pence; null when there is none.","type":["integer","null"]},"grossPayDisplay":{"description":"Gross pay for the period, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"incomeTaxMinor":{"description":"Income tax taken off, in whole pence; null when there is none.","type":["integer","null"]},"incomeTaxDisplay":{"description":"Income tax taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"nationalInsuranceMinor":{"description":"National Insurance taken off, in whole pence; null when there is none.","type":["integer","null"]},"nationalInsuranceDisplay":{"description":"National Insurance taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"pensionMinor":{"description":"Your pension contribution taken off, in whole pence; null when there is none.","type":["integer","null"]},"pensionDisplay":{"description":"Your pension contribution taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"studentLoanMinor":{"description":"Student loan repayment taken off, in whole pence; null when there is none.","type":["integer","null"]},"studentLoanDisplay":{"description":"Student loan repayment taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"otherDeductionsMinor":{"description":"Whatever its total deductions take besides the four above (a share scheme, a union), 0 when they are all of it, in whole pence; null when there is none.","type":["integer","null"]},"otherDeductionsDisplay":{"description":"Whatever its total deductions take besides the four above (a share scheme, a union), 0 when they are all of it, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"netPayMinor":{"description":"Net pay: what it says reached your bank, in whole pence; null when there is none.","type":["integer","null"]},"netPayDisplay":{"description":"Net pay: what it says reached your bank, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"yearToDate":{"type":"object","properties":{"grossPayMinor":{"description":"Gross pay in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"grossPayDisplay":{"description":"Gross pay in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"incomeTaxMinor":{"description":"Income tax in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"incomeTaxDisplay":{"description":"Income tax in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"nationalInsuranceMinor":{"description":"National Insurance in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"nationalInsuranceDisplay":{"description":"National Insurance in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"pensionMinor":{"description":"Pension contributions in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"pensionDisplay":{"description":"Pension contributions in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]}},"required":["grossPayMinor","grossPayDisplay","incomeTaxMinor","incomeTaxDisplay","nationalInsuranceMinor","nationalInsuranceDisplay","pensionMinor","pensionDisplay"],"description":"The tax year so far, as the payslip prints it.","additionalProperties":false}},"required":["employer","payDate","payPeriod","taxCode","grossPayMinor","grossPayDisplay","incomeTaxMinor","incomeTaxDisplay","nationalInsuranceMinor","nationalInsuranceDisplay","pensionMinor","pensionDisplay","studentLoanMinor","studentLoanDisplay","otherDeductionsMinor","otherDeductionsDisplay","netPayMinor","netPayDisplay","yearToDate"],"additionalProperties":false},{"type":"null"}],"description":"For a document read as a payslip: what it says, from the same figures Itemise salary uses. Deductions are positive, the money taken off. A value dismissed in the app is null. Never the National Insurance number. Null for anything not read as a payslip."}},"required":["formKind","readAt","current","merchant","date","totalMinor","totalDisplay","payslip"],"additionalProperties":false},{"type":"null"}],"description":"The headline values Read with AI found; `null` until a document has been read that way."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line, starts with `dli_`. A new reading gives every line a new id."},"position":{"type":"integer","description":"Its place in the reading’s lines, from 0."},"description":{"description":"What the line says, such as `Gross pay`. Account and card numbers are masked.","type":["string","null"]},"kind":{"anyOf":[{"type":"string","enum":["item","discount","subtotal","tax","service","tip","total","payment","change","other"]},{"type":"null"}],"description":"What the line is, where the reading labelled it: `item` or `discount` on a receipt or invoice. Null where it did not, as on a payslip, whose gross pay is positive and each deduction negative."},"quantity":{"description":"How many, where the line printed it.","type":["number","null"]},"unitPriceMinor":{"description":"The price of one, where the line printed it, in whole pence; null when there is none.","type":["integer","null"]},"unitPriceDisplay":{"description":"The price of one, where the line printed it, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"amountMinor":{"description":"The line’s amount as printed: an item positive, a discount or deduction negative, in whole pence; null when there is none.","type":["integer","null"]},"amountDisplay":{"description":"The line’s amount as printed: an item positive, a discount or deduction negative, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"status":{"type":"string","enum":["verified","found_elsewhere","unsupported","disputed","missing"],"description":"How sure the reading is of it: `verified` when it was found where the reading says."},"ofPosition":{"description":"A discount printed under its item (a loyalty price): that item’s `position`; null otherwise.","type":["integer","null"]},"dismissed":{"type":"boolean","description":"True when you said it is fine for it to be missing from the transaction."},"transactionLine":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The transaction line it is on."},"transactionId":{"type":"string","description":"The transaction that line is part of."},"linkSource":{"type":"string","enum":["create","itemise","user","paired"],"description":"How it got there: made by Create or Itemise, linked by you, or a pairing you kept."}},"required":["id","transactionId","linkSource"],"additionalProperties":false},{"type":"null"}],"description":"The transaction line this line is on. Null when it is on none, or the key cannot read transactions."}},"required":["id","position","description","kind","quantity","unitPriceMinor","unitPriceDisplay","amountMinor","amountDisplay","status","ofPosition","dismissed","transactionLine"],"additionalProperties":false},"description":"The lines its reading found, in order: a receipt’s items and discounts, a payslip’s gross pay and deductions. Empty until it has been read with AI, or when its reading was dismissed."}},"required":["id","title","titleSource","kind","source","mimeType","family","partCount","pageCount","sizeBytes","processingStatus","reviewStatus","linkCount","pair","date","createdAt","updatedAt","version","trashedAt","purgeAfter","snippet","originalFilename","notes","documentDate","documentTime","paidDate","paidFrom","capturedAt","processingError","links","pairMembers","suggestedPair","reading","lines"],"additionalProperties":false}}},"example":{"data":{"id":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","title":"Boots receipt","titleSource":"user","kind":"receipt","source":"shortcut","mimeType":"image/jpeg","family":"image","partCount":1,"pageCount":1,"sizeBytes":184320,"processingStatus":"processed","reviewStatus":"none","linkCount":1,"pair":null,"date":"2026-10-20","createdAt":"2026-10-20T14:03:11.000Z","updatedAt":"2026-10-20T14:05:40.000Z","version":"1792505140000","trashedAt":null,"purgeAfter":null,"snippet":null,"originalFilename":"IMG_2041.jpg","notes":null,"documentDate":null,"documentTime":null,"paidDate":null,"paidFrom":null,"capturedAt":"2026-10-20T14:02:51.000Z","processingError":null,"links":[{"id":"dln_0a7b9c1d-3e5f-4a6b-8c7d-9e0f1a2b3c4d","targetType":"transaction","targetId":"a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b","linkSource":"user","periodStart":null,"periodEnd":null}],"pairMembers":[],"suggestedPair":null,"reading":{"formKind":"receipt","readAt":"2026-10-20T14:06:02.000Z","current":true,"merchant":"Boots","date":"2026-10-20","totalMinor":1249,"totalDisplay":"£12.49","payslip":null},"lines":[{"id":"dli_5c2e8f1a-9b3d-4e7f-a6c0-1d2e3f4a5b6c","position":0,"description":"Vitamin D 90 tablets","kind":"item","quantity":1,"unitPriceMinor":null,"unitPriceDisplay":null,"amountMinor":1249,"amountDisplay":"£12.49","status":"verified","ofPosition":null,"dismissed":false,"transactionLine":{"id":"b7c1d2e3-f4a5-4b6c-8d7e-9f0a1b2c3d4e","transactionId":"a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b","linkSource":"paired"}}]}}}}},"400":{"description":"`validation_failed`: The body is empty, or `kind` is not one of the document kinds. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app, or the document does not exist or belongs to someone else or is in the Trash and must be restored first. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"deleteDocumentsById","tags":["documents"],"summary":"Move a document to the Trash","description":"Moves a document to the Trash. Its attachments stay, so restoring it puts it back where it was used; every list leaves it out until then, and the Trash removes it and its files for good after 30 days (`purgeAfter`). Send `If-Match` with the document’s `version` to refuse if it changed since you read it.\n\nNeeds the `documents:delete` scope.","x-required-scope":"documents:delete","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"responses":{"204":{"description":"Done. There is no body.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app, or the document does not exist or belongs to someone else or is already in the Trash. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{id}/text":{"get":{"operationId":"getDocumentsByIdText","tags":["documents"],"summary":"Read a document’s text","description":"The text read from each page: a PDF’s own text, the app’s reading of a photo, or Live Text from the phone. Account and card numbers are already masked to their last four. Very long documents stop at 50,000 characters (`truncated`). `pages` is empty for a document with no text yet.\n\nNeeds the `documents:read` scope.","x-required-scope":"documents:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The document id."},"source":{"description":"Where most of the text came from: the PDF’s own text, the app’s reading of the photo, or Live Text.","type":["string","null"]},"characters":{"type":"integer","description":"Length of all the text, even when `pages` stops short."},"pagesWithText":{"type":"integer","description":"How many pages have any text."},"truncated":{"type":"boolean","description":"True when long documents were cut to the first 50,000 characters."},"text":{"type":"string","description":"The pages joined with a blank line between them."},"pages":{"type":"array","items":{"type":"object","properties":{"page":{"type":"integer","description":"The page number, from 1."},"source":{"type":"string","description":"Where the text of this page came from."},"text":{"type":"string","description":"The text of the page."}},"required":["page","source","text"],"additionalProperties":false},"description":"The text page by page; stops short of `characters` when the text was cut."}},"required":["id","source","characters","pagesWithText","truncated","text","pages"],"additionalProperties":false}}},"example":{"data":{"id":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","source":"ocr","characters":61,"pagesWithText":1,"truncated":false,"text":"BOOTS PHARMACY\nVitamin D 90 tablets 12.49\nTotal 12.49","pages":[{"page":1,"source":"ocr","text":"BOOTS PHARMACY\nVitamin D 90 tablets 12.49\nTotal 12.49"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app, or the document does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"`unavailable`: The document vault is not answering.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/file":{"get":{"operationId":"getDocumentsByIdFile","tags":["documents"],"summary":"Download a document file","description":"Answers 302 to a link that works for about a minute, so send the request with `-L` (curl) and without the key on the second hop. Add `as=link` to get `{ url, expiresAt }` instead and fetch it yourself. The link is never cached or logged. Answers 503 `unavailable` (with `Retry-After`) while document storage is down; a file the storage no longer holds is a 404.\n\nNeeds the `documents:read` scope.","x-required-scope":"documents:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91"},{"name":"part","in":"query","required":false,"description":"Which file of a document with several photos, from 1. For `variant=page` it is the page.","schema":{"default":1,"type":"integer","minimum":1,"maximum":999}},{"name":"variant","in":"query","required":false,"description":"`original` (default), `model` (the copy used for reading), `page` (a PDF page as an image), `thumb` or `unlocked` (a password-protected PDF, unlocked).","schema":{"default":"original","type":"string","enum":["original","model","page","thumb","unlocked","display"]}},{"name":"download","in":"query","required":false,"description":"`true` to have the file saved rather than shown in a browser.","schema":{"type":"string","enum":["0","1","true","false"]}},{"name":"as","in":"query","required":false,"description":"`link` answers with `{ url, expiresAt }` instead of redirecting.","schema":{"type":"string","const":"link"},"example":"link"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string","description":"A short-lived address to download the file from."},"expiresAt":{"type":"string","description":"When the address stops working, ISO 8601 in UTC."}},"required":["url","expiresAt"],"description":"Only with `as=link`.","additionalProperties":false}}},"example":{"data":{"url":"https://files.example.com/…signed…","expiresAt":"2026-10-26T09:01:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app, the document or the `part` you asked for does not exist, or storage no longer holds the file. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"`unavailable`: Document storage is down or not set up; retry after the `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/uploads":{"post":{"operationId":"postDocumentsUploads","tags":["documents"],"summary":"Start an upload of any size","description":"Step 1 of an upload that does not fit in one request: declare the file (its type, size and SHA-256), then send its bytes to the `upload` form this returns, add any further pages with `POST /documents/{id}/parts`, and finish with `POST /documents/{id}/complete`. Declaring the same file again while it is unfinished gives the same upload back. A key always gets an upload; whether the file is already a document is only decided from its bytes at `complete`. Counts against the key’s 200 upload calls per UK day.\n\nNeeds the `documents:upload` scope.","x-required-scope":"documents:upload","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The file’s name, such as `IMG_2041.jpg`.","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"type":{"type":"string","maxLength":255,"description":"The MIME type: `image/jpeg`, `image/png`, `image/heic` or `application/pdf`."},"size":{"type":"integer","minimum":1,"maximum":26214400,"description":"The file’s size in bytes."},"sha256":{"type":"string","pattern":"^[0-9a-fA-F]{64}$","description":"The SHA-256 of the file’s bytes, in hex (64 characters)."},"clientOcrText":{"description":"Text read on the phone (Live Text). It only helps find the transaction.","anyOf":[{"type":"string","maxLength":100000},{"type":"null"}]}},"required":["type","size","sha256"],"additionalProperties":false},"example":{"name":"IMG_2041.jpg","type":"image/jpeg","size":184320,"sha256":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["upload","duplicate"],"description":"`upload` when the file should be sent to `upload`; `duplicate` when it is already a document."},"documentId":{"description":"The document being uploaded.","type":"string"},"part":{"description":"Always 1 here.","type":"integer"},"upload":{"description":"Send the file to this form (a `POST` of `fields` plus the file in `file`, or a `PUT` with `headers`) before it expires.","type":"object","properties":{"method":{"type":"string","enum":["POST","PUT"],"description":"The HTTP method to send the file with."},"url":{"type":"string","description":"The address to send the file to."},"fields":{"description":"`POST` only: form fields to send before the file.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"headers":{"description":"`PUT` only: headers to send with the file.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"expiresAt":{"type":"string","description":"When the form stops working, ISO 8601 in UTC."}},"required":["method","url","expiresAt"],"additionalProperties":false}},"required":["status"],"additionalProperties":false}}},"example":{"data":{"status":"upload","documentId":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","part":1,"upload":{"method":"POST","url":"https://files.example.com/upload","fields":{"key":"documents/…","policy":"…"},"expiresAt":"2026-10-26T09:10:00.000Z"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"description":"`rate_limited`: The key has used its 200 upload calls for the UK day (`reason: daily_limit`). The key has used up its rate limit; wait `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`unavailable`: Document storage is down or not set up; retry after the `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/parts":{"post":{"operationId":"postDocumentsByIdParts","tags":["documents"],"summary":"Add a page to an upload","description":"Another page for a photo document that is still uploading, up to 20 (a long receipt). Declare it like the first file, with `part` set to its page number (2 for the second); a retry sends the same number. Then send its bytes to the `upload` form this returns.\n\nNeeds the `documents:upload` scope.","x-required-scope":"documents:upload","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The file’s name, such as `IMG_2041.jpg`.","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"type":{"type":"string","maxLength":255,"description":"The MIME type: `image/jpeg`, `image/png`, `image/heic` or `application/pdf`."},"size":{"type":"integer","minimum":1,"maximum":26214400,"description":"The file’s size in bytes."},"sha256":{"type":"string","pattern":"^[0-9a-fA-F]{64}$","description":"The SHA-256 of the file’s bytes, in hex (64 characters)."},"clientOcrText":{"description":"Text read on the phone (Live Text). It only helps find the transaction.","anyOf":[{"type":"string","maxLength":100000},{"type":"null"}]},"part":{"type":"integer","minimum":2,"maximum":20,"description":"The page this file is: 2 for the second, and so on. A retry sends the same number."}},"required":["type","size","sha256","part"],"additionalProperties":false},"example":{"name":"IMG_2042.jpg","type":"image/jpeg","size":201776,"sha256":"2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae","part":2}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"documentId":{"type":"string","description":"The document this page belongs to."},"part":{"type":"integer","description":"The page number this upload is for."},"upload":{"type":"object","properties":{"method":{"type":"string","enum":["POST","PUT"],"description":"The HTTP method to send the file with."},"url":{"type":"string","description":"The address to send the file to."},"fields":{"description":"`POST` only: form fields to send before the file.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"headers":{"description":"`PUT` only: headers to send with the file.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"expiresAt":{"type":"string","description":"When the form stops working, ISO 8601 in UTC."}},"required":["method","url","expiresAt"],"description":"Where to send the file’s bytes.","additionalProperties":false}},"required":["documentId","part","upload"],"additionalProperties":false}}},"example":{"data":{"documentId":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","part":2,"upload":{"method":"POST","url":"https://files.example.com/upload","fields":{"key":"documents/…","policy":"…"},"expiresAt":"2026-10-26T09:10:00.000Z"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The upload does not exist, is not yours, or has already been finished. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"description":"`rate_limited`: The key has used its 200 upload calls for the UK day (`reason: daily_limit`). The key has used up its rate limit; wait `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`unavailable`: Document storage is down or not set up; retry after the `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/complete":{"post":{"operationId":"postDocumentsByIdComplete","tags":["documents"],"summary":"Finish an upload","description":"The last step of an upload: checks that every page arrived, then the document counts and lands in the Documents inbox. Safe to repeat. Answers 409 with `reason: not_uploaded` while a page is still on its way. The same file already in Documents is only found here, from its bytes: `duplicate`, without saying which document has it, and the upload is dropped.\n\nNeeds the `documents:upload` scope.","x-required-scope":"documents:upload","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["added","duplicate"],"description":"`added` for a new document, `duplicate` when the file was already there."},"documentId":{"description":"Not given for a duplicate.","type":"string"},"url":{"description":"Where the document opens in the app. Not given for a duplicate.","type":"string"}},"required":["status"],"additionalProperties":false}}},"example":{"data":{"status":"added","documentId":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","url":"https://finance.example.com/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/details"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app, or the upload does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: A page has not arrived yet (`reason: not_uploaded`); send it, then try again.\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"`unavailable`: Document storage is down or not set up; retry after the `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/links":{"post":{"operationId":"postDocumentsByIdLinks","tags":["documents"],"summary":"Attach a document","description":"Attaches a document to a transaction, an inbox item or an account. The key also needs to read the target’s area (`transactions:read`, `inbox:read` or `accounts:read`). Attaching it again where it already is changes nothing and answers 200 with the existing link; a new link answers 201. Attaching a captured document is the decision it waited for, so it leaves the Documents inbox. For an account, `periodStart` and `periodEnd` say which statement period the document covers.\n\nNeeds the `documents:write` scope.","x-required-scope":"documents:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetType":{"type":"string","enum":["transaction","account","inbox"],"description":"What to attach it to."},"targetId":{"type":"string","minLength":1,"maxLength":64,"description":"The transaction, account or inbox item."},"periodStart":{"description":"Accounts only: the first day of the statement period (`YYYY-MM-DD`).","type":"string"},"periodEnd":{"description":"Accounts only: the last day of the statement period.","type":"string"}},"required":["targetType","targetId"],"additionalProperties":false},"example":{"targetType":"transaction","targetId":"a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The link, starts with `dln_`."},"targetType":{"type":"string","enum":["transaction","inbox_item","account"],"description":"What kind of thing it is attached to."},"targetId":{"type":"string","description":"The transaction, inbox item or account it is attached to."},"linkSource":{"anyOf":[{"type":"string","enum":["user","auto_match","system"]},{"type":"null"}],"description":"Who attached it. Not given for accounts."},"periodStart":{"description":"Accounts only: the statement period, first day.","type":["string","null"]},"periodEnd":{"description":"Accounts only: the statement period, last day.","type":["string","null"]}},"required":["id","targetType","targetId","linkSource","periodStart","periodEnd"],"additionalProperties":false}}},"example":{"data":{"id":"dln_0a7b9c1d-3e5f-4a6b-8c7d-9e0f1a2b3c4d","targetType":"transaction","targetId":"a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b","linkSource":"user","periodStart":null,"periodEnd":null}}}}},"400":{"description":"`validation_failed`: `periodStart` or `periodEnd` is sent for something other than an account. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden_scope`: The key cannot also read the area of the target: `transactions:read`, `inbox:read` or `accounts:read`. The key lacks the `documents:write` scope; `requiredScope` names it.\n\n`forbidden`: The key is limited to some accounts, and this area spans all of them (`reason: account_limit`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: Documents are switched off for the whole app, or the document or the target does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{id}/links/{linkId}":{"delete":{"operationId":"deleteDocumentsByIdLinksByLinkId","tags":["documents"],"summary":"Detach a document","description":"Removes one attachment. The document stays in your Documents, Unfiled if nothing else uses it. `linkId` is the `id` of an entry in the document’s `links`.\n\nNeeds the `documents:write` scope.","x-required-scope":"documents:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91"},{"name":"linkId","in":"path","required":true,"description":"The attachment, starts with `dln_`.","schema":{"type":"string","pattern":"^dln_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"dln_0a7b9c1d-3e5f-4a6b-8c7d-9e0f1a2b3c4d"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"responses":{"204":{"description":"Done. There is no body.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The document or the link does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{id}/restore":{"post":{"operationId":"postDocumentsByIdRestore","tags":["documents"],"summary":"Restore a document from the Trash","description":"Brings a document back from the Trash while it is still there (`purgeAfter` has not passed), with its attachments. If the same file was added again meanwhile, that copy wins: the answer is a 409 `conflict` with `reason: duplicate`, naming the live document as `duplicateDocumentId` when the key can read documents. Answers with the document as `GET /documents/{id}` shows it.\n\nNeeds the `documents:write` scope.","x-required-scope":"documents:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The document, starts with `doc_`.","schema":{"type":"string","pattern":"^doc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"example":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name, else `Photo` or `PDF`."},"titleSource":{"anyOf":[{"type":"string","enum":["user","transaction"]},{"type":"null"}],"description":"What named it, when it was not the file."},"kind":{"type":"string","description":"`receipt`, `invoice`, `statement`, `payslip`, `tax`, `policy`, `warranty`, `letter`, `summary`, `other` or `unknown`."},"source":{"type":"string","enum":["upload","shortcut","share_target","email","system"],"description":"How it arrived."},"mimeType":{"type":"string","description":"The file type of the first file, such as `application/pdf`."},"family":{"type":"string","enum":["image","pdf"],"description":"Whether it is made of images or is a PDF."},"partCount":{"type":"integer","description":"Files that make it up: photos of a long receipt, say."},"pageCount":{"description":"How many pages it has, once known.","type":["integer","null"]},"sizeBytes":{"type":"integer","description":"All originals together, in bytes."},"processingStatus":{"type":"string","enum":["upload_pending","queued","processing","processed","needs_input","failed"],"description":"Where reading its text has got to: `processed` once done, `needs_input` when it waits for you, `failed` on an error."},"reviewStatus":{"type":"string","enum":["none","pending","done"],"description":"`pending` means it waits in the Documents inbox."},"linkCount":{"type":"integer","description":"Transactions, inbox items and accounts it is attached to. Only those the key can read are counted, as in `links`."},"pair":{"anyOf":[{"type":"object","properties":{"role":{"type":"string","enum":["lead","companion"],"description":"`lead`: the other files go with it (the receipt leads). `companion`: it goes with `leadId`."},"leadId":{"description":"For a companion, the document it goes with; null for a lead.","type":["string","null"]},"companionCount":{"type":"integer","description":"For a lead, how many other files are paired with it; 0 for a companion."},"state":{"type":"string","enum":["paired","suggested"],"description":"`paired`: attaching, detaching or filing one does them all. `suggested`: only offered, as “Same purchase as …?”."}},"required":["role","leadId","companionCount","state"],"additionalProperties":false},{"type":"null"}],"description":"The same purchase in other files, such as an invoice and its receipt from one email; null when it has none."},"date":{"description":"The day it is filed under, `YYYY-MM-DD`: the day it is dated when one is set (`documentDate`), else when it was taken, else when it arrived.","type":["string","null"]},"createdAt":{"description":"When it was added, ISO 8601 in UTC.","type":["string","null"]},"updatedAt":{"description":"When it last changed, ISO 8601 in UTC.","type":["string","null"]},"version":{"type":"string","description":"Changes whenever the document does."},"trashedAt":{"description":"Set while it is in the Trash.","type":["string","null"]},"purgeAfter":{"description":"When the Trash removes it for good.","type":["string","null"]},"snippet":{"description":"Where a search matched, as plain text.","type":["string","null"]},"originalFilename":{"description":"The name of the first file as it was uploaded.","type":["string","null"]},"notes":{"description":"Free-text notes.","type":["string","null"]},"documentDate":{"description":"The day it is dated, `YYYY-MM-DD`, when you or a suggested date you used set one; null when none is set.","type":["string","null"]},"documentTime":{"description":"The time of that day it is dated, `HH:MM` on the UK clock (Europe/London), when one is set with `documentDate` (a receipt’s printed time, say); null when none is. Documents on the same day are listed by it.","type":["string","null"]},"paidDate":{"description":"The day it was paid, `YYYY-MM-DD`: its transaction’s day when it’s attached to one (the latest, if several), else a day you set; null when not known. Shown only: `date` is what it’s filed under.","type":["string","null"]},"paidFrom":{"anyOf":[{"type":"string","enum":["transaction","you"]},{"type":"null"}],"description":"Where `paidDate` comes from: its transaction, or you."},"capturedAt":{"description":"When the photo or scan was taken, ISO 8601 in UTC, when known.","type":["string","null"]},"processingError":{"description":"Why reading it failed, when `processingStatus` is `failed`.","type":["string","null"]},"links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The link, starts with `dln_`."},"targetType":{"type":"string","enum":["transaction","inbox_item","account"],"description":"What kind of thing it is attached to."},"targetId":{"type":"string","description":"The transaction, inbox item or account it is attached to."},"linkSource":{"anyOf":[{"type":"string","enum":["user","auto_match","system"]},{"type":"null"}],"description":"Who attached it. Not given for accounts."},"periodStart":{"description":"Accounts only: the statement period, first day.","type":["string","null"]},"periodEnd":{"description":"Accounts only: the statement period, last day.","type":["string","null"]}},"required":["id","targetType","targetId","linkSource","periodStart","periodEnd"],"additionalProperties":false},"description":"What it is attached to. Only things the key can read are listed."},"pairMembers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name."},"role":{"type":"string","enum":["lead","companion"],"description":"`lead`: the one the pair goes by (the receipt)."}},"required":["id","title","role"],"additionalProperties":false},"description":"The rest of its pair, the lead first; empty when it is not paired."},"suggestedPair":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Starts with `doc_`."},"title":{"type":"string","description":"Its title, else the file’s name."}},"required":["id","title"],"additionalProperties":false},{"type":"null"}],"description":"A document from somewhere else offered as the same purchase, not yet paired; null when none."},"reading":{"anyOf":[{"type":"object","properties":{"formKind":{"description":"What it was read as: `receipt`, `invoice`, …","type":["string","null"]},"readAt":{"description":"When it was read, ISO 8601 in UTC.","type":["string","null"]},"current":{"type":"boolean","description":"False when the document was read again since this reading."},"merchant":{"description":"The shop or company the reading found.","type":["string","null"]},"date":{"description":"`YYYY-MM-DD`, when the reading found a date.","type":["string","null"]},"totalMinor":{"description":"The total found, in whole pence; null when none.","type":["integer","null"]},"totalDisplay":{"description":"Ready to show, such as `£12.50`.","type":["string","null"]},"payslip":{"anyOf":[{"type":"object","properties":{"employer":{"description":"Who paid you, as the payslip names them.","type":["string","null"]},"payDate":{"description":"The day it says you were paid, `YYYY-MM-DD`.","type":["string","null"]},"payPeriod":{"description":"The period it pays for, as printed, such as `October 2026` or `Week 28`.","type":["string","null"]},"taxCode":{"description":"The tax code it was worked out with, such as `1257L`.","type":["string","null"]},"grossPayMinor":{"description":"Gross pay for the period, in whole pence; null when there is none.","type":["integer","null"]},"grossPayDisplay":{"description":"Gross pay for the period, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"incomeTaxMinor":{"description":"Income tax taken off, in whole pence; null when there is none.","type":["integer","null"]},"incomeTaxDisplay":{"description":"Income tax taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"nationalInsuranceMinor":{"description":"National Insurance taken off, in whole pence; null when there is none.","type":["integer","null"]},"nationalInsuranceDisplay":{"description":"National Insurance taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"pensionMinor":{"description":"Your pension contribution taken off, in whole pence; null when there is none.","type":["integer","null"]},"pensionDisplay":{"description":"Your pension contribution taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"studentLoanMinor":{"description":"Student loan repayment taken off, in whole pence; null when there is none.","type":["integer","null"]},"studentLoanDisplay":{"description":"Student loan repayment taken off, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"otherDeductionsMinor":{"description":"Whatever its total deductions take besides the four above (a share scheme, a union), 0 when they are all of it, in whole pence; null when there is none.","type":["integer","null"]},"otherDeductionsDisplay":{"description":"Whatever its total deductions take besides the four above (a share scheme, a union), 0 when they are all of it, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"netPayMinor":{"description":"Net pay: what it says reached your bank, in whole pence; null when there is none.","type":["integer","null"]},"netPayDisplay":{"description":"Net pay: what it says reached your bank, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"yearToDate":{"type":"object","properties":{"grossPayMinor":{"description":"Gross pay in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"grossPayDisplay":{"description":"Gross pay in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"incomeTaxMinor":{"description":"Income tax in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"incomeTaxDisplay":{"description":"Income tax in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"nationalInsuranceMinor":{"description":"National Insurance in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"nationalInsuranceDisplay":{"description":"National Insurance in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"pensionMinor":{"description":"Pension contributions in the tax year so far, in whole pence; null when there is none.","type":["integer","null"]},"pensionDisplay":{"description":"Pension contributions in the tax year so far, ready to show, such as £12.50; null when there is none.","type":["string","null"]}},"required":["grossPayMinor","grossPayDisplay","incomeTaxMinor","incomeTaxDisplay","nationalInsuranceMinor","nationalInsuranceDisplay","pensionMinor","pensionDisplay"],"description":"The tax year so far, as the payslip prints it.","additionalProperties":false}},"required":["employer","payDate","payPeriod","taxCode","grossPayMinor","grossPayDisplay","incomeTaxMinor","incomeTaxDisplay","nationalInsuranceMinor","nationalInsuranceDisplay","pensionMinor","pensionDisplay","studentLoanMinor","studentLoanDisplay","otherDeductionsMinor","otherDeductionsDisplay","netPayMinor","netPayDisplay","yearToDate"],"additionalProperties":false},{"type":"null"}],"description":"For a document read as a payslip: what it says, from the same figures Itemise salary uses. Deductions are positive, the money taken off. A value dismissed in the app is null. Never the National Insurance number. Null for anything not read as a payslip."}},"required":["formKind","readAt","current","merchant","date","totalMinor","totalDisplay","payslip"],"additionalProperties":false},{"type":"null"}],"description":"The headline values Read with AI found; `null` until a document has been read that way."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The line, starts with `dli_`. A new reading gives every line a new id."},"position":{"type":"integer","description":"Its place in the reading’s lines, from 0."},"description":{"description":"What the line says, such as `Gross pay`. Account and card numbers are masked.","type":["string","null"]},"kind":{"anyOf":[{"type":"string","enum":["item","discount","subtotal","tax","service","tip","total","payment","change","other"]},{"type":"null"}],"description":"What the line is, where the reading labelled it: `item` or `discount` on a receipt or invoice. Null where it did not, as on a payslip, whose gross pay is positive and each deduction negative."},"quantity":{"description":"How many, where the line printed it.","type":["number","null"]},"unitPriceMinor":{"description":"The price of one, where the line printed it, in whole pence; null when there is none.","type":["integer","null"]},"unitPriceDisplay":{"description":"The price of one, where the line printed it, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"amountMinor":{"description":"The line’s amount as printed: an item positive, a discount or deduction negative, in whole pence; null when there is none.","type":["integer","null"]},"amountDisplay":{"description":"The line’s amount as printed: an item positive, a discount or deduction negative, ready to show, such as £12.50; null when there is none.","type":["string","null"]},"status":{"type":"string","enum":["verified","found_elsewhere","unsupported","disputed","missing"],"description":"How sure the reading is of it: `verified` when it was found where the reading says."},"ofPosition":{"description":"A discount printed under its item (a loyalty price): that item’s `position`; null otherwise.","type":["integer","null"]},"dismissed":{"type":"boolean","description":"True when you said it is fine for it to be missing from the transaction."},"transactionLine":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The transaction line it is on."},"transactionId":{"type":"string","description":"The transaction that line is part of."},"linkSource":{"type":"string","enum":["create","itemise","user","paired"],"description":"How it got there: made by Create or Itemise, linked by you, or a pairing you kept."}},"required":["id","transactionId","linkSource"],"additionalProperties":false},{"type":"null"}],"description":"The transaction line this line is on. Null when it is on none, or the key cannot read transactions."}},"required":["id","position","description","kind","quantity","unitPriceMinor","unitPriceDisplay","amountMinor","amountDisplay","status","ofPosition","dismissed","transactionLine"],"additionalProperties":false},"description":"The lines its reading found, in order: a receipt’s items and discounts, a payslip’s gross pay and deductions. Empty until it has been read with AI, or when its reading was dismissed."}},"required":["id","title","titleSource","kind","source","mimeType","family","partCount","pageCount","sizeBytes","processingStatus","reviewStatus","linkCount","pair","date","createdAt","updatedAt","version","trashedAt","purgeAfter","snippet","originalFilename","notes","documentDate","documentTime","paidDate","paidFrom","capturedAt","processingError","links","pairMembers","suggestedPair","reading","lines"],"additionalProperties":false}}},"example":{"data":{"id":"doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91","title":"Boots receipt","titleSource":"user","kind":"receipt","source":"shortcut","mimeType":"image/jpeg","family":"image","partCount":1,"pageCount":1,"sizeBytes":184320,"processingStatus":"processed","reviewStatus":"none","linkCount":1,"pair":null,"date":"2026-10-20","createdAt":"2026-10-20T14:03:11.000Z","updatedAt":"2026-10-20T14:05:40.000Z","version":"1792505140000","trashedAt":null,"purgeAfter":null,"snippet":null,"originalFilename":"IMG_2041.jpg","notes":null,"documentDate":null,"documentTime":null,"paidDate":null,"paidFrom":null,"capturedAt":"2026-10-20T14:02:51.000Z","processingError":null,"links":[{"id":"dln_0a7b9c1d-3e5f-4a6b-8c7d-9e0f1a2b3c4d","targetType":"transaction","targetId":"a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b","linkSource":"user","periodStart":null,"periodEnd":null}],"pairMembers":[],"suggestedPair":null,"reading":{"formKind":"receipt","readAt":"2026-10-20T14:06:02.000Z","current":true,"merchant":"Boots","date":"2026-10-20","totalMinor":1249,"totalDisplay":"£12.49","payslip":null},"lines":[{"id":"dli_5c2e8f1a-9b3d-4e7f-a6c0-1d2e3f4a5b6c","position":0,"description":"Vitamin D 90 tablets","kind":"item","quantity":1,"unitPriceMinor":null,"unitPriceDisplay":null,"amountMinor":1249,"amountDisplay":"£12.49","status":"verified","ofPosition":null,"dismissed":false,"transactionLine":{"id":"b7c1d2e3-f4a5-4b6c-8d7e-9f0a1b2c3d4e","transactionId":"a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b","linkSource":"paired"}}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: Documents are switched off for the whole app, or the document does not exist or belongs to someone else, is not in the Trash, or has been removed for good. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: The same file was added again while this one was in the Trash (`reason: duplicate`).\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/search":{"get":{"operationId":"getSearch","tags":["search"],"summary":"Search everything","description":"One search across transactions, accounts, payees, categories, tags, bills and documents, like the ⌘K palette. Results come grouped by kind, up to `limit` of each, best match first within a kind. A kind is only searched when the key can also read its area (`transactions:read` for transactions, and so on); the ones left out are named in `meta.omittedTypes`, as are documents while they are switched off.\n\nNeeds the `search:read` scope.","x-required-scope":"search:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"What to look for. Every word must match. At least 2 characters.","schema":{"type":"string","minLength":2,"maxLength":200},"example":"tesco"},{"name":"types","in":"query","required":false,"description":"Only these kinds of result, comma-separated: `transaction`, `account`, `payee`, `category`, `tag`, `bill`, `document` (plurals work too). Default: every kind the key can read.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"example":"transaction,payee"},{"name":"limit","in":"query","required":false,"description":"Results of each kind, 1 to 20. Default 5.","schema":{"default":5,"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["transaction","account","payee","category","tag","bill","document"],"description":"What sort of thing it is, such as `transaction` or `document`."},"id":{"type":"string","description":"The id to use with that type’s own endpoint, such as `GET /transactions/{id}`."},"title":{"type":"string","description":"Its name or description."},"subtitle":{"description":"A second line of context: the payee and account, the institution, the document kind.","type":["string","null"]},"date":{"description":"`YYYY-MM-DD`: a transaction’s or document’s day, a bill’s next due date.","type":["string","null"]},"amountMinor":{"description":"Whole pence, negative for money out. 0 for a transfer between your own accounts. `null` for things without an amount.","type":["integer","null"]},"amountDisplay":{"description":"The amount ready to show, or null.","type":["string","null"]}},"required":["type","id","title","subtitle","date","amountMinor","amountDisplay"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"type":"transaction","id":"a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b","title":"Tesco Express","subtitle":"Tesco · Current account","date":"2026-10-24","amountMinor":-1862,"amountDisplay":"-£18.62"},{"type":"payee","id":"payee_id","title":"Tesco","subtitle":"expense","date":null,"amountMinor":null,"amountDisplay":null}],"page":{"nextCursor":null,"hasMore":false}}}}},"400":{"description":"`validation_failed`: `q` is missing or too short, or `types` names something that cannot be searched. A query parameter is wrong, or not one this endpoint knows; `details` lists each.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inbox":{"get":{"operationId":"getInbox","tags":["inbox"],"summary":"List inbox items","description":"Wallet purchases waiting for review, oldest first, as the inbox works through them. Amounts are negative (money spent); `hasAmount` is false for a purchase that arrived without one. The suggested payee, category and account are what the app would pre-fill; they are only suggestions, nothing is approved by reading them. To keep a copy in step, send `updatedSince`: items that changed since then come back whatever their status, so one you approved or dismissed shows with that status. A dismissed item that is later deleted in the app no longer appears.\n\nNeeds the `inbox:read` scope.","x-required-scope":"inbox:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"updatedSince","in":"query","required":false,"description":"Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as `2026-10-24T18:30:00Z` (no offset means UK time; a plain date is the start of that UK day). Send the `page.asOf` of your last run (of its first page, if it took several), not the newest `updatedAt` you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check). Lists items of every status that changed (approved, dismissed and expired ones too, flagged by `status`), oldest first, and without suggestions for those no longer pending.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1 to 50. Default 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"example":"20"},{"name":"cursor","in":"query","required":false,"description":"`page.nextCursor` from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The inbox item id."},"status":{"type":"string","enum":["pending","approved","dismissed","expired"],"description":"`pending` waits for you; `approved` became a transaction; `dismissed` was thrown away; `expired` was left too long."},"merchant":{"type":"string","description":"The merchant as the wallet sent it."},"amountMinor":{"type":"integer","description":"Whole pence, negative for money spent. 0 when the purchase arrived without an amount."},"amountDisplay":{"type":"string","description":"The amount ready to show, such as -£4.80."},"hasAmount":{"type":"boolean","description":"False when the purchase arrived without an amount and waits for you to fill it in."},"original":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code charged, such as EUR."},"amountMinor":{"type":"integer","description":"The amount in that currency's minor unit (cents for EUR); negative for money spent."},"amountDisplay":{"type":"string","description":"That amount ready to show."}},"required":["currency","amountMinor","amountDisplay"],"additionalProperties":false},{"type":"null"}],"description":"What was charged in the merchant’s own currency, for a foreign purchase."},"date":{"description":"The day of the purchase (`YYYY-MM-DD`), when the wallet gave one.","type":["string","null"]},"card":{"description":"The card label the wallet sent, such as `Visa •• 4242`.","type":["string","null"]},"receivedAt":{"description":"When it reached the inbox.","type":["string","null"]},"suggestedPayee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee it will probably be filed under, if one was worked out."},"suggestedCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category it will probably be filed under, if one was worked out."},"suggestedAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The card or account the purchase probably came from."}},"required":["id","status","merchant","amountMinor","amountDisplay","hasAmount","original","date","card","receivedAt","suggestedPayee","suggestedCategory","suggestedAccount"],"additionalProperties":false}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"],"description":"Send as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean"},"asOf":{"type":"string","description":"Lists with an `updatedSince` filter only: the server time the read started. Store it and send it as the next `updatedSince`."}}}}},"example":{"data":[{"id":"wallet_import_id","status":"pending","merchant":"PRET A MANGER LONDON","amountMinor":-495,"amountDisplay":"-£4.95","hasAmount":true,"original":null,"date":"2026-10-24","card":"Visa •• 4242","receivedAt":"2026-10-24T12:31:07.000Z","suggestedPayee":{"id":"payee_id","name":"Pret A Manger"},"suggestedCategory":{"id":"category_id","name":"Eating out"},"suggestedAccount":{"id":"account_id","name":"Current account"}}],"page":{"nextCursor":null,"hasMore":false,"asOf":"2026-10-26T09:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"postInbox","tags":["inbox"],"summary":"Add a purchase to the inbox","description":"Queues a wallet purchase for review, like `POST /api/import/wallet` but with money in whole pence. Nothing is posted to the ledger yet unless one of your auto-approve rules trusts it, in which case `autoApproved` is true and the item is already `approved`. A key with `wallet:write` or `inbox:write` can use it. Send an `Idempotency-Key` header (or `idempotencyKey` in the body) so a retry never queues the purchase twice: the same key answers the item already queued, with `deduplicated: true` and a 200. The key is shared with `POST /api/import/wallet`, across API keys: a purchase queued there under the same key is answered here as a repeat, and the other way round. Suggested payee, category and account are included only when the key can also read the inbox and the area each suggestion comes from.\n\nNeeds the `wallet:write` scope.","x-required-scope":"wallet:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant":{"description":"The merchant or title shown in the inbox. Leave it out when the wallet cannot say.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"amountMinor":{"description":"Pence spent, as a positive whole number (`495` is £4.95). Leave it out, or send 0, for a purchase that arrived without an amount: it waits for you to fill it in.","anyOf":[{"type":"integer","minimum":0,"maximum":2147483647},{"type":"null"}]},"transactionDate":{"description":"The day of the purchase: `YYYY-MM-DD` or an ISO 8601 date-time (no offset means UK time). Wins over `date`. Dates like `05/10/2026` are refused: the day and month order would be a guess.","type":"string"},"date":{"description":"The same as `transactionDate`, for clients that call it this.","type":"string"},"card":{"description":"The card label the wallet sent, such as `Visa •• 4242`. It helps pick the account.","type":"string","maxLength":200},"name":{"description":"The name of the Shortcut sending this.","type":"string","maxLength":200},"idempotencyKey":{"description":"Makes a retry safe, like the `Idempotency-Key` header (send either; if both, they must match). A purchase already queued under this key is answered again, not queued twice.","type":"string","minLength":1,"maxLength":128},"metadata":{"description":"Anything else worth keeping with the purchase. Kept as sent and shown in its history.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"originalCurrency":{"anyOf":[{"type":"string","pattern":"^[A-Z]{3}$"},{"type":"null"}]},"originalAmountMinor":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"fxRate":{"anyOf":[{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":99999999},{"type":"string","maxLength":32}]},{"type":"null"}]},"fxSource":{"anyOf":[{"type":"string","enum":["manual","derived","frankfurter"]},{"type":"null"}]},"fxAsOf":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]}},"additionalProperties":false},"example":{"merchant":"PRET A MANGER LONDON","amountMinor":495,"transactionDate":"2026-10-24","card":"Visa •• 4242","name":"Add to JAG Finance","idempotencyKey":"7c1b6f4e-2d8a-4a39-9c53-0d1e2f3a4b5c"}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The inbox item id."},"status":{"type":"string","enum":["pending","approved","dismissed","expired"],"description":"`pending` waits for you; `approved` became a transaction; `dismissed` was thrown away; `expired` was left too long."},"merchant":{"type":"string","description":"The merchant as the wallet sent it."},"amountMinor":{"type":"integer","description":"Whole pence, negative for money spent. 0 when the purchase arrived without an amount."},"amountDisplay":{"type":"string","description":"The amount ready to show, such as -£4.80."},"hasAmount":{"type":"boolean","description":"False when the purchase arrived without an amount and waits for you to fill it in."},"original":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code charged, such as EUR."},"amountMinor":{"type":"integer","description":"The amount in that currency's minor unit (cents for EUR); negative for money spent."},"amountDisplay":{"type":"string","description":"That amount ready to show."}},"required":["currency","amountMinor","amountDisplay"],"additionalProperties":false},{"type":"null"}],"description":"What was charged in the merchant’s own currency, for a foreign purchase."},"date":{"description":"The day of the purchase (`YYYY-MM-DD`), when the wallet gave one.","type":["string","null"]},"card":{"description":"The card label the wallet sent, such as `Visa •• 4242`.","type":["string","null"]},"receivedAt":{"description":"When it reached the inbox.","type":["string","null"]},"suggestedPayee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee it will probably be filed under, if one was worked out."},"suggestedCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category it will probably be filed under, if one was worked out."},"suggestedAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The card or account the purchase probably came from."},"autoApproved":{"type":"boolean","description":"True when an auto-approve rule posted it straight away."},"deduplicated":{"type":"boolean","description":"True when this key had already queued the purchase, so nothing new was added."}},"required":["id","status","merchant","amountMinor","amountDisplay","hasAmount","original","date","card","receivedAt","suggestedPayee","suggestedCategory","suggestedAccount","autoApproved","deduplicated"],"additionalProperties":false}}},"example":{"data":{"id":"wallet_import_id","status":"pending","merchant":"PRET A MANGER LONDON","amountMinor":-495,"amountDisplay":"-£4.95","hasAmount":true,"original":null,"date":"2026-10-24","card":"Visa •• 4242","receivedAt":"2026-10-24T12:31:07.000Z","suggestedPayee":{"id":"payee_id","name":"Pret A Manger"},"suggestedCategory":{"id":"category_id","name":"Eating out"},"suggestedAccount":{"id":"account_id","name":"Current account"},"autoApproved":false,"deduplicated":false}}}}},"400":{"description":"`validation_failed`: The `Idempotency-Key` header and the `idempotencyKey` in the body differ, or the foreign-currency amounts do not add up. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inbox/{id}":{"get":{"operationId":"getInboxById","tags":["inbox"],"summary":"Get an inbox item","description":"One item with its alternatives and anything that looks like a repeat of it. Works for items already approved, dismissed or expired too. `transactionId` (once approved), the transaction ids in `possibleDuplicates` and `documents` appear only when the key can also read transactions or documents, and without `transactions:read` `possibleDuplicate` is true only for a repeat that is itself waiting in the inbox.\n\nNeeds the `inbox:read` scope.","x-required-scope":"inbox:read","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The inbox item.","schema":{"type":"string","minLength":1,"maxLength":64},"example":"wallet_import_id"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The inbox item id."},"status":{"type":"string","enum":["pending","approved","dismissed","expired"],"description":"`pending` waits for you; `approved` became a transaction; `dismissed` was thrown away; `expired` was left too long."},"merchant":{"type":"string","description":"The merchant as the wallet sent it."},"amountMinor":{"type":"integer","description":"Whole pence, negative for money spent. 0 when the purchase arrived without an amount."},"amountDisplay":{"type":"string","description":"The amount ready to show, such as -£4.80."},"hasAmount":{"type":"boolean","description":"False when the purchase arrived without an amount and waits for you to fill it in."},"original":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code charged, such as EUR."},"amountMinor":{"type":"integer","description":"The amount in that currency's minor unit (cents for EUR); negative for money spent."},"amountDisplay":{"type":"string","description":"That amount ready to show."}},"required":["currency","amountMinor","amountDisplay"],"additionalProperties":false},{"type":"null"}],"description":"What was charged in the merchant’s own currency, for a foreign purchase."},"date":{"description":"The day of the purchase (`YYYY-MM-DD`), when the wallet gave one.","type":["string","null"]},"card":{"description":"The card label the wallet sent, such as `Visa •• 4242`.","type":["string","null"]},"receivedAt":{"description":"When it reached the inbox.","type":["string","null"]},"suggestedPayee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee it will probably be filed under, if one was worked out."},"suggestedCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category it will probably be filed under, if one was worked out."},"suggestedAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The card or account the purchase probably came from."},"shortcutName":{"description":"The Shortcut that sent it, if one did.","type":["string","null"]},"alternatePayees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"Other payees it could be filed under."},"alternateCategories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"Other categories it could be filed under."},"alternateAccounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},"description":"Other accounts it could have come from."},"possibleDuplicate":{"type":"boolean","description":"True when the same purchase looks already recorded or queued."},"possibleDuplicates":{"type":"object","properties":{"transactionIds":{"type":"array","items":{"type":"string"},"description":"Only listed when the key can read transactions."},"inboxItemIds":{"type":"array","items":{"type":"string"},"description":"Other inbox items it looks like a repeat of."}},"required":["transactionIds","inboxItemIds"],"description":"What it looks like a repeat of.","additionalProperties":false},"transactionId":{"description":"The transaction it became, once approved. Only given when the key can read transactions.","type":["string","null"]},"documents":{"description":"Documents attached to it. Only present when the key can read documents.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The document id."},"title":{"type":"string","description":"The document title."}},"required":["id","title"],"additionalProperties":false}}},"required":["id","status","merchant","amountMinor","amountDisplay","hasAmount","original","date","card","receivedAt","suggestedPayee","suggestedCategory","suggestedAccount","shortcutName","alternatePayees","alternateCategories","alternateAccounts","possibleDuplicate","possibleDuplicates","transactionId"],"additionalProperties":false}}},"example":{"data":{"id":"wallet_import_id","status":"pending","merchant":"PRET A MANGER LONDON","amountMinor":-495,"amountDisplay":"-£4.95","hasAmount":true,"original":null,"date":"2026-10-24","card":"Visa •• 4242","receivedAt":"2026-10-24T12:31:07.000Z","suggestedPayee":{"id":"payee_id","name":"Pret A Manger"},"suggestedCategory":{"id":"category_id","name":"Eating out"},"suggestedAccount":{"id":"account_id","name":"Current account"},"shortcutName":"Add to JAG Finance","alternatePayees":[{"id":"payee_2","name":"Pret"}],"alternateCategories":[],"alternateAccounts":[],"possibleDuplicate":false,"possibleDuplicates":{"transactionIds":[],"inboxItemIds":[]},"transactionId":null}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"deleteInboxById","tags":["inbox"],"summary":"Delete a dismissed inbox item","description":"Removes an item you dismissed, for good. Documents still attached to it stay in your Documents, Unfiled. Only dismissed items can be deleted: a pending or approved one answers 404.\n\nNeeds the `inbox:delete` scope.","x-required-scope":"inbox:delete","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The inbox item.","schema":{"type":"string","minLength":1,"maxLength":64},"example":"wallet_import_id"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"responses":{"204":{"description":"Done. There is no body.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The item does not exist or belongs to someone else, or has not been dismissed. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inbox/{id}/approve":{"post":{"operationId":"postInboxByIdApprove","tags":["inbox"],"summary":"Approve an inbox item","description":"Posts a pending purchase to the ledger as an expense. Send only what you want to override: anything left out is filled from what the app has saved for this merchant (its payee, category and account), or the one card the label names. If the pocket, category or payee still cannot be told, nothing is posted and the answer is a 400 naming the fields to send. The choices are saved as the merchant’s mapping, as approving in the app does. The answer is the item, now `approved`, with the `transactionId` it became; `amountMinor` is what was posted. Answers 404 for an unknown item and 409 `not_pending` for one already approved, dismissed or expired. A purchase in a foreign currency with no exchange rate yet must be approved in the app.\n\nNeeds the `inbox:write` scope.","x-required-scope":"inbox:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The inbox item.","schema":{"type":"string","minLength":1,"maxLength":64},"example":"wallet_import_id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"categoryId":{"description":"The category to post under. Left out, the one saved for this merchant is used.","type":"string","minLength":1,"maxLength":64},"payeeId":{"description":"The payee. Left out, the one saved for this merchant is used.","type":"string","minLength":1,"maxLength":64},"accountId":{"description":"The card or pot it was paid from, or a financial account id to use its Direct source. Left out, the saved one, or the one card the label names, is used.","type":"string","minLength":1,"maxLength":64},"description":{"description":"The transaction’s description. Left out, the merchant as the wallet sent it.","type":"string","minLength":1,"maxLength":2000},"amountMinor":{"description":"Pence to post, as a positive whole number. Needed when the purchase arrived without an amount; also corrects one.","type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"additionalProperties":false},"example":{"categoryId":"category_id","description":"Lunch with Sam"}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The inbox item id."},"status":{"type":"string","enum":["pending","approved","dismissed","expired"],"description":"`pending` waits for you; `approved` became a transaction; `dismissed` was thrown away; `expired` was left too long."},"merchant":{"type":"string","description":"The merchant as the wallet sent it."},"amountMinor":{"type":"integer","description":"Whole pence, negative for money spent. 0 when the purchase arrived without an amount."},"amountDisplay":{"type":"string","description":"The amount ready to show, such as -£4.80."},"hasAmount":{"type":"boolean","description":"False when the purchase arrived without an amount and waits for you to fill it in."},"original":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code charged, such as EUR."},"amountMinor":{"type":"integer","description":"The amount in that currency's minor unit (cents for EUR); negative for money spent."},"amountDisplay":{"type":"string","description":"That amount ready to show."}},"required":["currency","amountMinor","amountDisplay"],"additionalProperties":false},{"type":"null"}],"description":"What was charged in the merchant’s own currency, for a foreign purchase."},"date":{"description":"The day of the purchase (`YYYY-MM-DD`), when the wallet gave one.","type":["string","null"]},"card":{"description":"The card label the wallet sent, such as `Visa •• 4242`.","type":["string","null"]},"receivedAt":{"description":"When it reached the inbox.","type":["string","null"]},"suggestedPayee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee it will probably be filed under, if one was worked out."},"suggestedCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category it will probably be filed under, if one was worked out."},"suggestedAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The card or account the purchase probably came from."},"transactionId":{"type":"string","description":"The transaction it became. Read it with `GET /transactions/{id}` (needs `transactions:read`)."}},"required":["id","status","merchant","amountMinor","amountDisplay","hasAmount","original","date","card","receivedAt","suggestedPayee","suggestedCategory","suggestedAccount","transactionId"],"additionalProperties":false}}},"example":{"data":{"id":"wallet_import_id","status":"approved","merchant":"PRET A MANGER LONDON","amountMinor":-495,"amountDisplay":"-£4.95","hasAmount":true,"original":null,"date":"2026-10-24","card":"Visa •• 4242","receivedAt":"2026-10-24T12:31:07.000Z","suggestedPayee":{"id":"payee_id","name":"Pret A Manger"},"suggestedCategory":{"id":"category_id","name":"Eating out"},"suggestedAccount":{"id":"account_id","name":"Current account"},"transactionId":"a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b"}}}}},"400":{"description":"`validation_failed`: The account, category or payee cannot be worked out (`reason: missing_fields`; `details` names what to send), or the purchase has no amount. A body field is missing, wrong, or not one this endpoint knows; `details` lists each.\n\n`invalid_json`: The body is not valid JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The item does not exist or belongs to someone else, or an account, category or payee you sent does not. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: The item is not pending: it was already approved, dismissed or has expired (`reason: not_pending`).\n\n`idempotency_in_progress`: A call with the same `Idempotency-Key` is still running; wait, then retry.\n\n`idempotency_outcome_unknown`: The first call with this `Idempotency-Key` may have completed but its answer was lost; check the data before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inbox/{id}/dismiss":{"post":{"operationId":"postInboxByIdDismiss","tags":["inbox"],"summary":"Dismiss an inbox item","description":"Sets a pending purchase aside without posting anything. It stays in the app’s dismissed list, where it can be restored, until it is deleted with `DELETE /inbox/{id}`. Answers 404 once the item is no longer pending.\n\nNeeds the `inbox:write` scope.","x-required-scope":"inbox:write","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The inbox item.","schema":{"type":"string","minLength":1,"maxLength":64},"example":"wallet_import_id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The inbox item id."},"status":{"type":"string","enum":["pending","approved","dismissed","expired"],"description":"`pending` waits for you; `approved` became a transaction; `dismissed` was thrown away; `expired` was left too long."},"merchant":{"type":"string","description":"The merchant as the wallet sent it."},"amountMinor":{"type":"integer","description":"Whole pence, negative for money spent. 0 when the purchase arrived without an amount."},"amountDisplay":{"type":"string","description":"The amount ready to show, such as -£4.80."},"hasAmount":{"type":"boolean","description":"False when the purchase arrived without an amount and waits for you to fill it in."},"original":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"The three-letter currency code charged, such as EUR."},"amountMinor":{"type":"integer","description":"The amount in that currency's minor unit (cents for EUR); negative for money spent."},"amountDisplay":{"type":"string","description":"That amount ready to show."}},"required":["currency","amountMinor","amountDisplay"],"additionalProperties":false},{"type":"null"}],"description":"What was charged in the merchant’s own currency, for a foreign purchase."},"date":{"description":"The day of the purchase (`YYYY-MM-DD`), when the wallet gave one.","type":["string","null"]},"card":{"description":"The card label the wallet sent, such as `Visa •• 4242`.","type":["string","null"]},"receivedAt":{"description":"When it reached the inbox.","type":["string","null"]},"suggestedPayee":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The payee it will probably be filed under, if one was worked out."},"suggestedCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The category it will probably be filed under, if one was worked out."},"suggestedAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Its id."},"name":{"type":"string","description":"Its name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The card or account the purchase probably came from."}},"required":["id","status","merchant","amountMinor","amountDisplay","hasAmount","original","date","card","receivedAt","suggestedPayee","suggestedCategory","suggestedAccount"],"additionalProperties":false}}},"example":{"data":{"id":"wallet_import_id","status":"dismissed","merchant":"PRET A MANGER LONDON","amountMinor":-495,"amountDisplay":"-£4.95","hasAmount":true,"original":null,"date":"2026-10-24","card":"Visa •• 4242","receivedAt":"2026-10-24T12:31:07.000Z","suggestedPayee":{"id":"payee_id","name":"Pret A Manger"},"suggestedCategory":{"id":"category_id","name":"Eating out"},"suggestedAccount":{"id":"account_id","name":"Current account"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found`: The item does not exist or belongs to someone else, or is no longer pending. Nothing exists with that id, or it belongs to someone else.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer sk_…`"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"`x-api-key: sk_…`"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["unauthorized","key_expired","key_revoked","forbidden_scope","forbidden","not_found","method_not_allowed","conflict","idempotency_in_progress","idempotency_outcome_unknown","version_conflict","payload_too_large","unsupported_media_type","validation_failed","invalid_json","idempotency_conflict","rate_limited","internal","unavailable"]},"message":{"type":"string"},"details":{"type":"array","description":"For `validation_failed`: one entry per field that is wrong.","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}},"requiredScope":{"type":"string","description":"For `forbidden_scope`: the scope the call needed."},"docs":{"type":"string","format":"uri","description":"For `not_found` and `method_not_allowed`: where the docs list the endpoints."},"suggestions":{"type":"array","description":"For `not_found`: the endpoints the address was probably meant to be, closest first. For `method_not_allowed`: the methods this address takes.","items":{"type":"object","required":["method","path","summary","docs"],"properties":{"method":{"type":"string"},"path":{"type":"string"},"summary":{"type":"string"},"docs":{"type":"string","format":"uri"}}}},"requestId":{"type":"string"}}}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique value (a UUID is fine). Repeating the call with the same key within 24 hours replays the first answer instead of doing it twice. Changing the key’s access (scopes or account limit) forgets its stored answers.","schema":{"type":"string","maxLength":255}},"IfMatch":{"name":"If-Match","in":"header","required":false,"description":"The item's `version`. If someone changed it since, the call fails with 412 instead of overwriting.","schema":{"type":"string"}}},"headers":{"XRequestId":{"description":"Unique id of this request; quote it when asking for help.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"The request is not valid (`validation_failed`, `invalid_json`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"No key, or a key that is wrong, expired or revoked (`unauthorized`, `key_expired`, `key_revoked`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks the scope this call needs (`forbidden_scope`), or may not do this (`forbidden`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Nothing exists at this address (`not_found`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"The change clashes with the current state, or the same Idempotency-Key is still running.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PreconditionFailed":{"description":"The `If-Match` version is out of date (`version_conflict`). Read it again and retry.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"The body is over the size limit (`payload_too_large`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnsupportedMediaType":{"description":"The body is not JSON (`unsupported_media_type`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The Idempotency-Key was already used with a different request (`idempotency_conflict`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"The key used up its rate limit (`rate_limited`). Wait for `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"A service this call needs is down for the moment (`unavailable`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}