Developers
JAG Finance API
Read and change your own money from scripts, Shortcuts and other tools: accounts, transactions, bills, budgets, goals, documents and more, 90 endpoints in all. Every page here is generated from the code, so it always matches what the API does.
Contents
Guides
Getting startedApple ShortcutsAuthenticationErrorsPagingSyncingMoneyDatesIdempotencyVersionsRate limitsScopesTypeScript clientWebhooksEndpoints
All endpointsMeta6
Accounts6
Transactions9
Categories5
Bills15
- GETWhat is due soon
- GETRecurring bills and income
- GETOne recurring series
- GETScheduled one-off items
- GETOne scheduled item
- POSTSchedule a one-off payment
- PATCHChange a scheduled item
- POSTPost a scheduled item to the ledger
- POSTCancel a scheduled item
- POSTCreate a recurring bill or income
- PATCHChange a recurring series
- POSTPause a recurring series
- POSTResume a recurring series
- POSTPost a recurring occurrence to the ledger
- POSTSkip a recurring occurrence
Budgets5
Goals5
Documents15
- POSTAdd a payslip to a payment
- GETList documents
- GETSearch documents by meaning
- GETGet a document
- GETRead a document’s text
- GETDownload a document file
- POSTUpload a document in one request
- POSTStart an upload of any size
- POSTAdd a page to an upload
- POSTFinish an upload
- PATCHChange a document’s details
- POSTAttach a document
- DELETEDetach a document
- DELETEMove a document to the Trash
- POSTRestore a document from the Trash
Inbox6
Insights8
Search1
Getting started
- Create a key in Settings → API keys, giving it only the access it needs. Its secret starts
sk_and is shown once. - Send it with every call, as below.
- Every endpoint lives under the base address. Tools can read the whole API from the OpenAPI file; it needs no key.
https://finance.jagwebsites.xyz/api/v1curl https://finance.jagwebsites.xyz/api/v1/me \
-H 'Authorization: Bearer sk_your_key'Apple Shortcuts
Shortcuts can read and change your money with one action, Get Contents of URL. Make a key in Settings first and give it only what the shortcut needs: reading insights for the first recipe below, writing transactions for the second. The key goes in the shortcut, so treat the shortcut like the key and do not share it.
Every call is the same four steps
- Add Get Contents of URL, tap URL and type the address of the endpoint, such as
https://finance.jagwebsites.xyz/api/v1/me. - Tap Show More and choose the Method:
GETto read,POSTto add something. - Under Headers add one: the key
Authorizationand the textBearer sk_your_key, with your own key after the word Bearer and a space. - To send details (a POST), set Request Body to JSON and add a field for each one. Pick the field type with care: money is a Number, everything else Text.
The answer is JSON. Add Get Dictionary Value, choose Value for data in Contents of URL, and that is what you asked for. If something went wrong the answer has error instead, and error then message says why in words.
Money: to show an amount, use the field ending Display (it already reads £12.50). To add amounts up or to send one, use Minor: whole pence, so £12.50 is 1250.
Recipe 1: How much have I spent today?
Needs the insights:read scope (the older totals:read works too).
- Current Date.
- Format Date: Date Format Custom, format
yyyy-MM-dd. This gives today as2026-10-26. - Text:
https://finance.jagwebsites.xyz/api/v1/insights/totals?from=, then the Formatted Date variable, then&to=, then the Formatted Date again. - Get Contents of URL with that Text as the URL, Method
GETand theAuthorizationheader. - Get Dictionary Value: Value for
data. It is a list with one entry, the whole day. - Get Item from List: First Item.
- Get Dictionary Value: Value for
spendingDisplay. - Show Result (or Speak Text to have Siri say it).
Recipe 2: Add a cash expense
Needs the transactions:write scope. Look up three ids once, from the Try it panels below or by running the list calls (GET /accounts, GET /categories, GET /payees), and paste them into the shortcut: your cash account, the category and the payee to file the expense under.
- Ask for Input: type Number, prompt
How much?. - Calculate: Provided Input ×
100, then Round Number to Ones Place. That is the amount in pence. - Ask for Input: type Text, prompt
What was it?. - Current Date, then Format Date as
yyyy-MM-dd. - Get Contents of URL: URL
https://finance.jagwebsites.xyz/api/v1/transactions, MethodPOST, theAuthorizationheader, Request Body JSON with the fields shown beside this:date,description,kind(expense),accountId,categoryId,payeeIdandamountMinoras a Number. - Get Dictionary Value: Value for
data, then again foramountDisplay. - Show Notification with that amount, so you see what was recorded.
The shorthand (accountId, amountMinor, categoryId, payeeId in the body itself) is for a transaction with one line. A shopping trip with several lines uses lines instead; see Create a transaction below.
GET https://finance.jagwebsites.xyz/api/v1/insights/totals?from=2026-10-26&to=2026-10-26
Authorization: Bearer sk_your_key{
"data": [
{
"start": "2026-10-26",
"end": "2026-10-26",
"incomeMinor": 0,
"incomeDisplay": "£0.00",
"spendingMinor": 1250,
"spendingDisplay": "£12.50",
"netMinor": -1250,
"netDisplay": "-£12.50",
"lineCount": 1
}
]
}{
"date": "2026-10-26",
"description": "Coffee",
"kind": "expense",
"accountId": "acc_cash",
"categoryId": "cat_eating_out",
"payeeId": "pay_cafe",
"amountMinor": 380
}Authentication
Send the key in either header. They are equivalent, so use whichever your tool makes easier.
A missing or wrong key gets 401. A key that is valid but lacks the scope a call needs gets 403 with requiredScope naming it. Keep keys out of URLs, screenshots and shared scripts; revoke one in Settings if it leaks.
Authorization: Bearer sk_your_key
# or
x-api-key: sk_your_keyErrors
Every error has the same shape. code is stable, so match on it rather than on message. details points at the fields that were wrong. Quote requestId (also sent as X-Request-Id) if you need help.
An address that is not an endpoint answers 404 not_found with a docs link and, when it is nearly right (a typo, a singular, a segment too many), suggestions: the endpoints it was probably meant to be, with your ids filled in.
A query parameter or body field the endpoint doesn’t know answers 400 validation_failed, with a detail per key and a “did you mean” hint (?limt=5 is refused rather than quietly giving the default page). Cache-busting parameters are the exception and are ignored: any name starting with _, and cb, cachebust, nocache, ts and timestamp.
unauthorized401No key was sent, or the key is not valid.key_expired401The key has passed its expiry date. Create a new one.key_revoked401The key was revoked. Create a new one.forbidden_scope403The key lacks the scope this call needs; requiredScope names it.forbidden403The key is valid and has the scope, but may not do this.not_found404Nothing exists at this address, or it belongs to someone else.method_not_allowed405The address exists but not for this method; Allow lists the right ones.conflict409The change clashes with the current state, such as a name already in use.idempotency_in_progress409A call with the same Idempotency-Key is still running. Wait, then retry.idempotency_outcome_unknown409The first call with this Idempotency-Key may have completed but its answer was lost. Check the data before retrying.version_conflict412The If-Match version is out of date. Read the item again and retry.payload_too_large413The request body is over the 1 MB limit.unsupported_media_type415Send the body as JSON with Content-Type: application/json.validation_failed400An input is not valid; details lists each field and what is wrong.invalid_json400The body is not valid JSON.idempotency_conflict422The Idempotency-Key was already used with a different request.rate_limited429The key has used up its rate limit; wait Retry-After seconds.internal500Something went wrong on our side. Quote the request id.unavailable503A service this call needs is down for the moment. Retry shortly.
{
"error": {
"code": "validation_failed",
"message": "The request is not valid.",
"details": [
{
"path": "query.limit",
"message": "Number must be less than or equal to 100"
}
],
"requestId": "req_01h…"
}
}Paging
Lists answer with the items in data and a page object. While hasMore is true, send nextCursor back as the cursor query parameter to get the next page. Treat a cursor as opaque, and keep the other filters the same between pages. limit sets the page size.
{
"data": [
"…"
],
"page": {
"nextCursor": "eyJ…",
"hasMore": true
}
}Syncing
Lists take updatedSince and answer page.asOf, so a script that keeps a copy can fetch only what changed since its last run:
- The first time, fetch everything (follow
nextCursor) and store thepage.asOfof the first page. - Next time, send that value as
updatedSince, update your copy by id, and store the newpage.asOf.
Store asOf, not the newest updatedAt you saw. It is a few seconds before the read, so a change saved while you were reading is not missed; an item may come back twice, which updating by id takes care of.
Items archived, closed, cancelled or put in the Trash since then come back with that state. Deleted items (transactions, tags, emptied Trash) are not listed: compare ids now and then for a full check. Changing a transaction's tags counts as a change to it, but deleting a tag altogether does not move the transactions that had it. Figures worked out from other data (balances, goal progress, budget spending, tag counts) change without their item changing, so read those again when you need them.
curl 'https://finance.jagwebsites.xyz/api/v1/transactions?updatedSince=2026-10-26T09%3A00%3A00Z' \
-H 'Authorization: Bearer sk_your_key'
# → { "data": [ … ], "page": { "nextCursor": null,
# "hasMore": false, "asOf": "2026-10-26T18:29:55.000Z" } }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. Add up the …Minor fields in scripts; show the …Display ones in Shortcuts. Requests only take the …Minor form. Money going out is negative.
{
"amountMinor": -1250,
"amountDisplay": "-£12.50"
}Dates
A calendar day is YYYY-MM-DD in UK time (Europe/London), such as 2026-10-26. A from or to filter given as a day covers the whole UK day. An instant (when something happened or changed) is ISO 8601 in UTC, such as 2026-10-26T09:00:00.000Z.
curl 'https://finance.jagwebsites.xyz/api/v1/transactions?from=2026-10-01&to=2026-10-26' \
-H 'Authorization: Bearer sk_your_key'Idempotency
Any call that changes data accepts an Idempotency-Key header: a unique value per intended action, such as a UUID. If a call is retried with the same key and the same request within 24 hours, you get the first answer back instead of the change happening twice. Changing a key’s access (its permissions or the accounts it is limited to) forgets its stored answers, so a retry after that runs again under the new access.
A retry while the first is still running gets 409 idempotency_in_progress; the same key with a different request gets 422 idempotency_conflict. In the rare case that the change was made but its answer could not be saved, the key answers 409 idempotency_outcome_unknown: look at your data before sending it again.
curl -X POST https://finance.jagwebsites.xyz/api/v1/tags \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 6f1d2c4e-8a5b-4f7e-9c3d-2b1a0e9f8d7c' \
-H 'Content-Type: application/json' \
-d '{
"name": "Household"
}'Versions
Items you can edit carry a version, also sent as the ETag header. It changes with every edit; treat it as opaque. Send it back as If-Match on PATCH, PUT and DELETE. If someone changed the item since you read it, the call fails with 412 version_conflict and changes nothing; read it again and retry.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/tags/tag_1 \
-H 'Authorization: Bearer sk_your_key' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"name": "Home"
}'Rate limits
Each key may make 1,000 requests an hour and no more than 120 in any minute by default. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). Past the limit you get 429 rate_limited with a Retry-After header; wait that many seconds. Calls refused for a missing scope do not count.
RateLimit-Limit: 1000
RateLimit-Remaining: 997
RateLimit-Reset: 1260Scopes
A key holds only the scopes you gave it, and a call outside them gets 403. Each area has read, write and delete. Scopes marked Shortcut-only are the narrow ones kept from before this API, made for Shortcuts and widgets: they open nothing beyond their own endpoints, and the broader scope named beside them opens the same endpoints too.
Keys limited to some accounts
A key can also be limited to chosen accounts in Settings → API keys, together with their cards and pots. It then sees only those accounts and the transactions and bills on them, and anything else answers 404 as if it did not exist. A transfer to another account still shows both lines, with the other one's account as { "id": null, "name": "Another account" }, so totals add up; the CSV export names it Another account too. That hidden line still shows its amount (and any foreign amount), category, payee, item name and notes: only which account it is on is left out. A write that would touch another account gets 403 forbidden naming the accounts the key may use, and in a batch one such item refuses the whole batch. Categories, payees and tags are shared and work as usual, except that a tag's transactionCount counts only the key's own transactions and a tag on a transaction elsewhere can't be deleted. Budgets, goals, insights, search, documents and the inbox span every account, so a limited key gets 403 forbidden there, and its transactions never list attached documents. GET /me shows the limit as accountLimit.
The limit is read when a request starts. Changing it in Settings applies to the next request; one already running (a long export, say) keeps the old limit until it ends.
accounts:readRead accounts. Institutions, accounts, cards and pots, balances and balance checks.
- GET
/accounts - GET
/accounts/{id} - GET
/institutions - GET
/accounts/{id}/balance-checks
- GET
accounts:writeChange accounts. Rename, close or set keep-aside on accounts; record balance checks.
- POST
/accounts/{id}/balance-checks - PATCH
/accounts/{id}
- POST
transactions:readRead transactions. Transactions, their lines and tags.
- GET
/transactions - GET
/transactions/lines - GET
/transactions/{id} - GET
/transactions/export
- GET
transactions:writeChange transactions. Create and edit transactions, their notes and tags.
- POST
/transactions - PATCH
/transactions/{id} - PUT
/transactions/{id}/tags - POST
/transactions/batch
- POST
transactions:deleteDelete transactions. Delete transactions.
- DELETE
/transactions/{id}
- DELETE
bills:readRead bills. Upcoming bills, recurring payments and scheduled items.
- GET
/bills/upcoming - GET
/recurring - GET
/recurring/{id} - GET
/scheduled - GET
/scheduled/{id}
- GET
bills:writeChange bills. Create and edit them; post, skip, pause and resume.
- POST
/scheduled - PATCH
/scheduled/{id} - POST
/scheduled/{id}/post - POST
/recurring - PATCH
/recurring/{id} - POST
/recurring/{id}/pause - POST
/recurring/{id}/resume - POST
/recurring/{id}/occurrences/{dueOn}/post - POST
/recurring/{id}/occurrences/{dueOn}/skip
- POST
bills:deleteDelete bills. Cancel scheduled items.
- POST
/scheduled/{id}/cancel
- POST
budgets:readRead budgets. Budgets and how much is left.
- GET
/budgets - GET
/budgets/{id}
- GET
budgets:writeChange budgets. Create budgets and set their amounts.
- POST
/budgets - PATCH
/budgets/{id} - PUT
/budgets/{id}/months/{month}
- POST
goals:readRead goals. Goals and their funding.
- GET
/goals - GET
/goals/{id}
- GET
goals:writeChange goals. Create and edit goals; add funding.
- POST
/goals - PATCH
/goals/{id} - POST
/goals/{id}/funding
- POST
categories:readRead categories. Categories and categorisation rules.
- GET
/categories - GET
/categories/{id} - GET
/rules
- GET
categories:writeChange categories. Create, edit and archive categories.
- POST
/categories - PATCH
/categories/{id}
- POST
payees:readRead payees. Payees.
- GET
/payees - GET
/payees/{id}
- GET
payees:writeChange payees. Create, edit, archive and restore payees.
- POST
/payees - PATCH
/payees/{id}
- POST
tags:readRead tags. Tags.
- GET
/tags - GET
/tags/{id}
- GET
tags:writeChange tags. Create and rename tags.
- POST
/tags - PATCH
/tags/{id}
- POST
tags:deleteDelete tags. Delete tags.
- DELETE
/tags/{id}
- DELETE
documents:readRead documents. Documents, their text and files.
- GET
/documents - GET
/documents/search - GET
/documents/{id} - GET
/documents/{id}/text - GET
/documents/{id}/file
- GET
documents:writeChange documents. Upload documents, edit their details and links, restore them.
- PATCH
/documents/{id} - POST
/documents/{id}/links - DELETE
/documents/{id}/links/{linkId} - POST
/documents/{id}/restore
- PATCH
documents:deleteDelete documents. Move documents to the trash.
- DELETE
/documents/{id}
- DELETE
inbox:readRead inbox. Wallet purchases waiting for review.
- GET
/inbox - GET
/inbox/{id}
- GET
inbox:writeChange inbox. Add, approve and dismiss them.
- POST
/inbox/{id}/approve - POST
/inbox/{id}/dismiss
- POST
inbox:deleteDelete inbox. Delete dismissed items.
- DELETE
/inbox/{id}
- DELETE
insights:readRead insights. Totals, cash flow, spending, net worth, forecasts and summaries.
- GET
/insights/cash-flow - GET
/insights/spending - GET
/insights/net-worth - GET
/insights/forecast - GET
/insights/runway - GET
/summaries - GET
/summaries/{id}
- GET
search:readRead search. Search across the areas this key can read.
- GET
/search
- GET
totals:readShortcut-onlyRead totals. Income and spending totals only (widgets).
Opens just its own endpoints. Also granted by
insights:read, never the other way round.- GET
/insights/totals
- GET
wallet:writeShortcut-onlyAdd wallet spend. Send a purchase to the inbox, nothing else (the wallet Shortcut).
Opens just its own endpoints. Also granted by
inbox:write, never the other way round.- POST
/inbox
- POST
documents:uploadShortcut-onlyAdd documents. Upload photos and PDFs to the Documents inbox, nothing else (the iPhone Shortcut).
Opens just its own endpoints. Also granted by
documents:write, never the other way round.- POST
/connection/payslips - POST
/documents - POST
/documents/uploads - POST
/documents/{id}/parts - POST
/documents/{id}/complete
- POST
TypeScript client
Scripts get autocomplete and types without writing them by hand. Download client.ts (it needs no key) into your project and import it. It is one file with no dependencies, generated from the same code as this page, so every request and answer is typed. Download it again whenever the API changes.
Each endpoint is a method named like its operation id (getTransactions, patchTagsById) that takes one object, { params, query, body }, plus idempotencyKey or ifMatch where they apply, and returns the typed data. Lists return { data, page, meta } and have an …All twin that follows the cursor for you; the CSV export returns its text. Any error answer throws a JagFinanceApiError with status, code, message, details, requestId and suggestions. It works in Node 18+, Deno, Bun and browsers (keep the key out of pages other people can open).
curl -o jag-finance.ts https://finance.jagwebsites.xyz/api/v1/client.tsimport { createJagFinanceClient } from './jag-finance';
const api = createJagFinanceClient({ apiKey: process.env['JAG_FINANCE_API_KEY']! });
const { data, page } = await api.getTransactions({
query: { from: '2026-10-01', limit: 20 },
});
console.log(data[0]?.description, page.hasMore);
// Writes take a body, and an Idempotency-Key to make a retry safe.
await api.postTags({ body: { name: 'Household' }, idempotencyKey: crypto.randomUUID() });// Follows nextCursor until the last page.
for await (const transaction of api.getTransactionsAll({ query: { from: '2026-01-01' } })) {
console.log(transaction.date, transaction.amountDisplay);
}import { JagFinanceApiError } from './jag-finance';
try {
await api.patchTagsById({ params: { id }, body: { name: 'Home' }, ifMatch: version });
} catch (error) {
if (error instanceof JagFinanceApiError && error.code === 'version_conflict') {
// Changed since you read it: read again and retry.
} else {
throw error; // error.status, error.code and error.requestId say what went wrong
}
}Webhooks
Instead of asking for changes, have them sent to you. Add an endpoint under Settings → API keys → Webhooks: a public https URL, the events it wants and a description. You can have up to 10. Each endpoint gets a signing secret starting whsec_, shown once; rotating it shows a new one once.
transaction.created: Added in the app, over the API, by an import, from the wallet inbox or by a rule. Also sent when a deleted transaction is put back.transaction.updated: Any change to a transaction or its lines, tags or notes.transaction.deleted: Only the id is sent.inbox.item.created: A wallet purchase arrived for review.document.attached: A document was attached to a transaction. Only ids are sent.document.detached: A document was taken off a transaction. Only ids are sent.webhook.test: sent when you press Send test event.
What is sent
Each event is a POST with a JSON body: id (also in the JAG-Event-Id header), type, createdAt and data.object. For transactions the object is what GET /transactions/{id} answers, money in …Minor and …Display; for transaction.deleted it is just { "id": … }. Inbox items are shaped as GET /inbox lists them, without suggestions. A change that is undone before it is saved (a failed save, say) is never sent. Several changes to one transaction in a single save make one event. Webhooks belong to you rather than to a key, so they cover every account, even if your keys are limited to some.
Checking the signature
JAG-Signature holds t= (Unix seconds) and v1=, the hex HMAC-SHA256 of <t>.<raw body> keyed with the whole secret, whsec_ included. Compute it over the body exactly as received, compare in constant time, and refuse a t more than 5 minutes old.
Answering
Reply with any 2xx within 10 seconds (5 seconds while your endpoint is failing); do the work afterwards if it takes longer. Redirects are not followed and count as failures. After a failure your endpoint is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, then every 12 hours, and newer events wait behind the one that failed, so they still arrive in order. Each event is tried up to seven times, then given up. An event still waiting to go out 24 hours after the change (after an outage on our side, say) is dropped rather than sent late, and if thousands are waiting for your endpoints, new ones are not queued until they clear. Delivery is at least once, and a redelivery you ask for can arrive out of order, so use JAG-Event-Id to skip an event you have already handled, and fetch the transaction if you need its latest state.
Failing endpoints
Every attempt (status, time taken, error and the first 1 KB of your answer) is listed under Recent deliveries for 30 days, where you can send any event again (a few a minute, and one at a time per endpoint). A test event that gets through lets anything waiting go straight away. Changing an endpoint's URL drops what was waiting for the old one. An endpoint where every delivery has failed for three days is switched off, with the reason shown in Settings; switch it back on once it works.
POST /webhooks/jag-finance HTTP/1.1
Content-Type: application/json
User-Agent: JAG-Finance-Webhooks/1
JAG-Event-Id: evt_5f2c9a1b7e3d4c6a8b0e1f2a
JAG-Event-Type: transaction.created
JAG-Signature: t=1761309300,v1=5b0c2e4f…{
"id": "evt_5f2c9a1b7e3d4c6a8b0e1f2a",
"type": "transaction.created",
"createdAt": "2026-10-24T12:35:00.000Z",
"data": {
"object": {
"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"
}
}
}import { createHmac, timingSafeEqual } from 'node:crypto';
// Pass the body exactly as it arrived (with Express: express.raw({ type: 'application/json' })).
export function verifyJagSignature(rawBody, header, secret) {
// A request without the header did not come from JAG Finance.
if (typeof header !== 'string' || !header) return false;
const parts = Object.fromEntries(header.split(',').map((part) => part.split('=', 2)));
const timestamp = Number(parts.t);
if (!Number.isInteger(timestamp) || !parts.v1) return false;
// Refuse anything signed more than 5 minutes ago: it may be a replay.
if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest();
const given = Buffer.from(parts.v1, 'hex');
return given.length === expected.length && timingSafeEqual(given, expected);
}
// verifyJagSignature(req.body, req.get('JAG-Signature'), signingSecret)import hashlib
import hmac
import time
def verify_jag_signature(raw_body: bytes, header: str | None, secret: str) -> bool:
if not header:
return False
parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
try:
timestamp = int(parts["t"])
except (KeyError, ValueError):
return False
# Refuse anything signed more than 5 minutes ago: it may be a replay.
if abs(time.time() - timestamp) > 300:
return False
signed = f"{timestamp}.".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
given = parts.get("v1", "")
# compare_digest refuses non-ASCII text with an error rather than answering False.
if not given.isascii():
return False
return hmac.compare_digest(expected, given)
# Flask: verify_jag_signature(request.get_data(), request.headers.get("JAG-Signature"), signing_secret)All endpoints
Meta
- GET
/meThe key making the requestAny key - GET
/connectionThe app’s connectionAny key - PUT
/connection/webhookSet the app’s webhookAny key - DELETE
/connection/webhookRemove the app’s webhookAny key - GET
/openapi.jsonThe OpenAPI 3.1 description of this APINo key needed - GET
/client.tsA ready-made TypeScript client for this APINo key needed
Accounts
- GET
/accountsList accountsaccounts:read - GET
/accounts/{id}Get an accountaccounts:read - GET
/institutionsList institutionsaccounts:read - GET
/accounts/{id}/balance-checksList an account's balance checksaccounts:read - POST
/accounts/{id}/balance-checksRecord a balance checkaccounts:write - PATCH
/accounts/{id}Rename, close or keep aside an accountaccounts:write
Transactions
- GET
/transactionsList transactionstransactions:read - GET
/transactions/linesList transaction linestransactions:read - GET
/transactions/{id}Get a transactiontransactions:read - POST
/transactionsCreate a transactiontransactions:write - PATCH
/transactions/{id}Edit a transactiontransactions:write - PUT
/transactions/{id}/tagsSet a transaction’s tagstransactions:write - DELETE
/transactions/{id}Delete a transactiontransactions:delete - POST
/transactions/batchCreate many transactions at oncetransactions:write - GET
/transactions/exportExport transactions as CSVtransactions:read
Categories
Payees
Tags
Bills
- GET
/bills/upcomingWhat is due soonbills:read - GET
/recurringRecurring bills and incomebills:read - GET
/recurring/{id}One recurring seriesbills:read - GET
/scheduledScheduled one-off itemsbills:read - GET
/scheduled/{id}One scheduled itembills:read - POST
/scheduledSchedule a one-off paymentbills:write - PATCH
/scheduled/{id}Change a scheduled itembills:write - POST
/scheduled/{id}/postPost a scheduled item to the ledgerbills:write - POST
/scheduled/{id}/cancelCancel a scheduled itembills:delete - POST
/recurringCreate a recurring bill or incomebills:write - PATCH
/recurring/{id}Change a recurring seriesbills:write - POST
/recurring/{id}/pausePause a recurring seriesbills:write - POST
/recurring/{id}/resumeResume a recurring seriesbills:write - POST
/recurring/{id}/occurrences/{dueOn}/postPost a recurring occurrence to the ledgerbills:write - POST
/recurring/{id}/occurrences/{dueOn}/skipSkip a recurring occurrencebills:write
Budgets
Goals
Documents
- POST
/connection/payslipsAdd a payslip to a paymentdocuments:upload - GET
/documentsList documentsdocuments:read - GET
/documents/searchSearch documents by meaningdocuments:read - GET
/documents/{id}Get a documentdocuments:read - GET
/documents/{id}/textRead a document’s textdocuments:read - GET
/documents/{id}/fileDownload a document filedocuments:read - POST
/documentsUpload a document in one requestdocuments:upload - POST
/documents/uploadsStart an upload of any sizedocuments:upload - POST
/documents/{id}/partsAdd a page to an uploaddocuments:upload - POST
/documents/{id}/completeFinish an uploaddocuments:upload - PATCH
/documents/{id}Change a document’s detailsdocuments:write - POST
/documents/{id}/linksAttach a documentdocuments:write - DELETE
/documents/{id}/links/{linkId}Detach a documentdocuments:write - DELETE
/documents/{id}Move a document to the Trashdocuments:delete - POST
/documents/{id}/restoreRestore a document from the Trashdocuments:write
Inbox
Insights
- GET
/insights/totalsIncome, spending and net for a rangetotals:read - GET
/insights/cash-flowCash flow over timeinsights:read - GET
/insights/spendingWhere the money wentinsights:read - GET
/insights/net-worthNet worth and how it changedinsights:read - GET
/insights/forecastCash forecast and safe to spendinsights:read - GET
/insights/runwayCash runwayinsights:read - GET
/summariesPeriod summariesinsights:read - GET
/summaries/{id}One period summaryinsights:read
Meta
6 endpoints
The key making the request
/api/v1/meWho 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).
Response fields
keyobjectrequiredThe key making the request.
key.idstringrequiredThe key id (not the secret).
key.namestring | nullrequiredThe name you gave the key.
key.scopesstring[]requiredWhat the key may do, such as
accounts:read.key.createdAtstring | nullrequiredWhen the key was created, ISO 8601 in UTC.
key.expiresAtstring | nullrequiredWhen the key stops working, ISO 8601 in UTC; null if it never does.
key.lastUsedAtstring | nullrequiredWhen the key was last used, ISO 8601 in UTC; null if never.
userobjectrequiredWho the key belongs to.
Errors
unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/me \
-H 'Authorization: Bearer sk_your_key'{
"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
}
}The app’s connection
/api/v1/connectionFor a connected app (OAuth token): what the person allowed it, the accounts it can see and its webhook. A key gets 403.
Response fields
grantIdstringrequiredThe connection.
appobjectrequiredThe app it is for.
app.clientIdstringrequiredIts client id, such as
jag-work.app.namestringrequiredIts name.
scopesstring[]requiredWhat the app may do.
accountsobject[]requiredThe accounts the person allowed it to see.
accounts[].idstringrequiredThe account id.
accounts[].namestringrequiredIts name.
Errors
unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/connection \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Set the app’s webhook
/api/v1/connection/webhookMakes 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.
Request body (JSON)
urlstringrequiredWhere to send events: an https address.
Response fields
idstringrequiredThe webhook.
urlstring | nullrequiredWhere events go.
eventsstring[]requiredWhat it is told about.
secretstringrequiredSigns each request (
JAG-Signature). Store it; it is not shown again.
Errors
validation_failed400A body field is missing, wrong, or not one this endpoint knows;
detailslists each.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PUT https://finance.jagwebsites.xyz/api/v1/connection/webhook \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://work.example.com/api/finance/webhook"
}'{
"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_…"
}
}Remove the app’s webhook
/api/v1/connection/webhookStops sending events to the connection’s webhook.
Errors
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X DELETE https://finance.jagwebsites.xyz/api/v1/connection/webhook \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"'204 with no body.
The OpenAPI 3.1 description of this API
/api/v1/openapi.jsonEvery 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.
Response fields
openapistringrequiredThe OpenAPI version,
3.1.0.infoobjectrequiredAbout the API.
info.titlestringrequiredThe name of the API.
info.versionstringrequiredThe version of the API.
serversobject[]requiredWhere the API is served.
servers[].urlstringrequiredThe base address of the API.
pathsobjectrequiredEvery endpoint, by path then method.
componentsobjectrequiredShared schemas, parameters and responses the endpoints refer to.
curl https://finance.jagwebsites.xyz/api/v1/openapi.json{
"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": {}
}A ready-made TypeScript client for this API
/api/v1/client.tsOne 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.
curl https://finance.jagwebsites.xyz/api/v1/client.tsexport function createJagFinanceClient(options: JagFinanceClientOptions) {
// …one method per endpoint, such as getTransactions({ query })
}Accounts
6 endpoints
List accounts
/api/v1/accountsEvery 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.
Query parameters
closed"exclude" | "include" | "only"Closed accounts:
exclude(default),includeoronly. WithupdatedSincethe default isinclude, so a closing shows.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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).
Response fields
idstringrequiredThe account id.
namestringrequiredThe account name.
institutionobjectrequiredThe bank or provider it is held with.
institution.idstringrequiredIts id.
institution.namestringrequiredIts name.
kind"current" | "savings" | "credit" | "cash"requiredWhat sort of account it is.
subtype"savings_pot" | nullrequiredsavings_potfor a pot inside another account; otherwise null.currencystringrequiredThe account currency, such as GBP.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
accounts:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/accounts \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Get an account
/api/v1/accounts/{id}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.
Path parameters
idstringrequiredThe account id.
Response fields
idstringrequiredThe account id.
namestringrequiredThe account name.
institutionobjectrequiredThe bank or provider it is held with.
institution.idstringrequiredIts id.
institution.namestringrequiredIts name.
kind"current" | "savings" | "credit" | "cash"requiredWhat sort of account it is.
subtype"savings_pot" | nullrequiredsavings_potfor a pot inside another account; otherwise null.currencystringrequiredThe account currency, such as GBP.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
accounts:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/accounts/acc_current \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}
}List institutions
/api/v1/institutionsBanks, 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).
Query parameters
updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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).
Response fields
idstringrequiredThe institution id.
namestringrequiredThe institution name.
closedbooleanrequiredTrue once it has been closed.
accountIdsstring[]requiredThe ids of its accounts.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
accounts:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/institutions \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}List an account's balance checks
/api/v1/accounts/{id}/balance-checksThe 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.
Path parameters
idstringrequiredThe account id.
Response fields
idstringrequiredThe balance check id.
accountIdstringrequiredThe account it was recorded against.
observedOnstringrequiredThe UK calendar day the provider balance was read.
observedAtstring | nullrequiredThe exact moment, when it was recorded (older checks have only the day).
matchesbooleanrequiredTrue when the provider balance equals the ledger balance.
notestring | nullrequiredA short note added with the check.
resolvedbooleanrequiredTrue once a difference has been marked as dealt with.
resolvedAtstring | nullrequiredWhen it was marked resolved, ISO 8601 in UTC.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
accounts:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/accounts/acc_current/balance-checks \
-H 'Authorization: Bearer sk_your_key'{
"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
}
}Record a balance check
/api/v1/accounts/{id}/balance-checksRecords 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.
Path parameters
idstringrequiredThe account id.
Request body (JSON)
observedMinorintegerrequiredThe balance the bank or provider showed, in pence. Negative when money is owed.
observedOnstringThe UK day it was read,
YYYY-MM-DD, today or earlier. Covers the whole day; preferobservedAtwhen you know the time.observedAtstring (date-time)The exact moment it was read, an ISO 8601 time such as
2026-10-24T08:30:00Z.notestring | nullA short note.
Response fields
idstringrequiredThe balance check id.
accountIdstringrequiredThe account it was recorded against.
observedOnstringrequiredThe UK calendar day the provider balance was read.
observedAtstring | nullrequiredThe exact moment, when it was recorded (older checks have only the day).
matchesbooleanrequiredTrue when the provider balance equals the ledger balance.
notestring | nullrequiredA short note added with the check.
resolvedbooleanrequiredTrue once a difference has been marked as dealt with.
resolvedAtstring | nullrequiredWhen it was marked resolved, ISO 8601 in UTC.
Errors
validation_failed400Neither
observedAtnorobservedOnis sent, or the time is in the future. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404Nothing exists with that id, or it belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
accounts:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/accounts/acc_current/balance-checks \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"observedMinor": 123450,
"observedAt": "2026-10-20T08:30:00Z",
"note": "From the app"
}'{
"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"
}
}Rename, close or keep aside an account
/api/v1/accounts/{id}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.
Path parameters
idstringrequiredThe account id.
Request body (JSON)
namestringA new name.
closedbooleanTrue closes the account; false reopens it. The default cash account cannot be closed.
keepAsidebooleanTrue leaves the account out of planning cash (Safe to spend, Forecast, Runway). Credit accounts cannot be kept aside.
versionstringThe
versionyou last read, as an alternative to theIf-Matchheader.
Response fields
idstringrequiredThe account id.
namestringrequiredThe account name.
institutionobjectrequiredThe bank or provider it is held with.
institution.idstringrequiredIts id.
institution.namestringrequiredIts name.
kind"current" | "savings" | "credit" | "cash"requiredWhat sort of account it is.
subtype"savings_pot" | nullrequiredsavings_potfor a pot inside another account; otherwise null.currencystringrequiredThe account currency, such as GBP.
Errors
validation_failed400The body is empty, or
keepAsideis set on a credit account. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404Nothing exists with that id, or it belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
accounts:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/accounts/acc_current \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"name": "Everyday account",
"keepAside": false
}'{
"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"
}
}
}Transactions
9 endpoints
List transactions
/api/v1/transactionsTransactions 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.
Query parameters
fromstringEarliest date, inclusive.
YYYY-MM-DD(a whole UK day) or an ISO 8601 timestamp.tostringLatest date, inclusive.
YYYY-MM-DDruns to the end of that UK day; a timestamp is that instant.accountIdstringA payment source (card, pot or account activity) id, or a financial account id for all of its sources.
categoryIdstringOnly transactions with a line in this category or any category under it (a parent category includes its subcategories, as on the Transactions page).
payeeIdstringOnly transactions with a line for this payee or any payee under it (a parent payee includes its sub-payees).
tagIdstringOnly transactions carrying this tag.
kind"expense" | "income" | "transfer"Expense, income or transfer, read from all of a transaction’s lines as the app does.
minAmountMinorintegerSmallest absolute amount in pence, up to 2147483647.
maxAmountMinorintegerLargest absolute amount in pence, up to 2147483647.
qstringText search over the description, notes and item names, with the same AND / OR / NOT, "quotes" and accent folding as the Transactions page.
hasDocuments"0" | "1" | "true" | "false"truefor transactions with documents attached,falsefor those without. Needs thedocuments:readscope and a key for all accounts.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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 asversion); 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.include"documents"documentsadds each transaction’s attached documents (id and title). Needs thedocuments:readscope and a key for all accounts.limitintegerTransactions per page, 1–200 (50 by default).
cursorstringpage.nextCursorfrom the previous page.
Response fields
idstringrequiredThe transaction id.
datestringrequiredThe day it happened, YYYY-MM-DD in UK time.
atstringrequiredThe moment it happened, ISO 8601 in UTC.
descriptionstringrequiredWhat the transaction is called.
descriptionAutobooleanrequiredTrue when the app writes the description from the lines, and rewrites it when they change.
notesstring | nullrequiredFree-text notes.
kind"expense" | "income" | "transfer"requiredWhether money went out, came in, or moved between your own accounts.
isTransferbooleanrequiredTrue for a move between your own accounts.
Errors
validation_failed400fromis afterto,minAmountMinoris abovemaxAmountMinor, or thecursoris not one a previous page gave. A query parameter is wrong, or not one this endpoint knows;detailslists each.forbidden_scope403hasDocumentsis used without thedocuments:readscope. The key lacks thetransactions:readscope;requiredScopenames it.forbidden403hasDocumentsorinclude=documentsis used by a key limited to some accounts (reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/transactions?from=2026-10-01&kind=expense&limit=20' \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}List transaction lines
/api/v1/transactions/linesOne 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).
Query parameters
fromstringEarliest date, inclusive.
YYYY-MM-DD(a whole UK day) or an ISO 8601 timestamp.tostringLatest date, inclusive.
YYYY-MM-DDruns to the end of that UK day; a timestamp is that instant.accountIdstringA payment source (card, pot or account activity) id, or a financial account id for all of its sources.
categoryIdstringOnly transactions with a line in this category or any category under it (a parent category includes its subcategories, as on the Transactions page).
payeeIdstringOnly transactions with a line for this payee or any payee under it (a parent payee includes its sub-payees).
tagIdstringOnly transactions carrying this tag.
kind"expense" | "income" | "transfer"Expense, income or transfer, read from all of a transaction’s lines as the app does.
minAmountMinorintegerSmallest absolute amount in pence, up to 2147483647.
maxAmountMinorintegerLargest absolute amount in pence, up to 2147483647.
qstringText search over the description, notes and item names, with the same AND / OR / NOT, "quotes" and accent folding as the Transactions page.
hasDocuments"0" | "1" | "true" | "false"truefor transactions with documents attached,falsefor those without. Needs thedocuments:readscope and a key for all accounts.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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.limitintegerLines per page, 1–200 (50 by default).
cursorstringpage.nextCursorfrom the previous page.
Response fields
idstringrequiredThe line id.
accountobjectrequiredThe 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" }.account.idstring | nullrequiredIts id; null for another account, to a key limited to some accounts.
account.namestringrequiredIts name.
amountMinorintegerrequiredAmount of this line in pence; negative is money out.
amountDisplaystringrequiredAmount of this line ready to show, such as -£12.50.
kind"item" | "adjustment" | "surcharge"requireditemis something bought;adjustmenta discount or correction;surchargea fee or tip.categoryobject | nullrequiredThe line's category, or null when it has none.
Errors
validation_failed400fromis afterto,minAmountMinoris abovemaxAmountMinor, or thecursoris not one a previous page gave. A query parameter is wrong, or not one this endpoint knows;detailslists each.forbidden_scope403hasDocumentsis used without thedocuments:readscope. The key lacks thetransactions:readscope;requiredScopenames it.forbidden403hasDocumentsorinclude=documentsis used by a key limited to some accounts (reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/transactions/lines?from=2026-10-01&limit=20' \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Get a transaction
/api/v1/transactions/{id}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.
Path parameters
idstringrequiredThe transaction id.
Response fields
idstringrequiredThe transaction id.
datestringrequiredThe day it happened, YYYY-MM-DD in UK time.
atstringrequiredThe moment it happened, ISO 8601 in UTC.
descriptionstringrequiredWhat the transaction is called.
descriptionAutobooleanrequiredTrue when the app writes the description from the lines, and rewrites it when they change.
notesstring | nullrequiredFree-text notes.
kind"expense" | "income" | "transfer"requiredWhether money went out, came in, or moved between your own accounts.
isTransferbooleanrequiredTrue for a move between your own accounts.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
transactions:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/transactions/txn_1 \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Create a transaction
/api/v1/transactionsPosts 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.
Request body (JSON)
datestringrequiredThe transaction’s date:
YYYY-MM-DD(stored at midday UK time on that day) or an ISO 8601 timestamp for an exact moment.descriptionstringWhat the transaction was, such as
Weekly shop. Leave it out and the app writes one from the lines, such asBought 3 items at Corner Market for £43.50, and keeps it up to date.descriptionStyle"smart" | "long" | "short"For a description the app writes:
long(Bought 3 items at Corner Market for £43.50),short(3 items · Corner Market · £43.50) orsmart(long when it fits in 60 characters). Defaults to your Settings choice.descriptionShowAmountbooleanFor a description the app writes: whether it includes the amount. Defaults to your Settings choice.
notesstring | nullPrivate notes on the transaction;
nullclears them.kind"expense" | "income" | "transfer"requiredexpensetakes money out,incomeputs money in,transfermoves it between two of your accounts.tagIdsstring[]Tag ids. The transaction ends up with exactly these tags.
linesobject[]The lines of an expense or income. Use these, or the single-line shorthand (
accountId,amountMinor,categoryId,payeeId), not both.accountIdstringSingle-line shorthand instead of
lines. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.amountMinorintegerSingle-line shorthand: the amount in pence (zero allowed). For a transfer, the amount moved.
categoryIdstringSingle-line shorthand: the category.
payeeIdstringSingle-line shorthand: the payee.
fromAccountIdstringTransfers only: where the money leaves. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.
toAccountIdstringTransfers only: where the money arrives. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.
Response fields
idstringrequiredThe transaction id.
datestringrequiredThe day it happened, YYYY-MM-DD in UK time.
atstringrequiredThe moment it happened, ISO 8601 in UTC.
descriptionstringrequiredWhat the transaction is called.
descriptionAutobooleanrequiredTrue when the app writes the description from the lines, and rewrites it when they change.
notesstring | nullrequiredFree-text notes.
kind"expense" | "income" | "transfer"requiredWhether money went out, came in, or moved between your own accounts.
isTransferbooleanrequiredTrue for a move between your own accounts.
Errors
validation_failed400The 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;
detailslists each.not_found404An account, category, payee or tag in the body does not exist or belongs to someone else.
idempotency_conflict422The ledger already holds a post under this
Idempotency-Keyfor a different transaction. TheIdempotency-Keywas already used with a different request.forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.forbidden_scope403The key lacks the
transactions:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/transactions \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"date": "2026-10-24",
"description": "Weekly shop",
"kind": "expense",
"tagIds": [
"tag_1"
],
"accountId": "src_1",
"amountMinor": 4210,
"categoryId": "cat_1",
"payeeId": "pay_1"
}'{
"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"
}
}Edit a transaction
/api/v1/transactions/{id}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.
Path parameters
idstringrequiredThe transaction id.
Request body (JSON)
datestringThe transaction’s date:
YYYY-MM-DD(stored at midday UK time on that day) or an ISO 8601 timestamp for an exact moment.descriptionstring | nullA new description;
nullhands it back to the app, which writes it from the lines.descriptionStyle"smart" | "long" | "short"For a description the app writes:
long(Bought 3 items at Corner Market for £43.50),short(3 items · Corner Market · £43.50) orsmart(long when it fits in 60 characters). Defaults to your Settings choice.descriptionShowAmountbooleanFor a description the app writes: whether it includes the amount. Defaults to your Settings choice.
notesstring | nullPrivate notes on the transaction;
nullclears them.kind"expense" | "income" | "transfer"Change the kind. Send
lines(or the transfer fields) with it, since the amounts change sign.tagIdsstring[]Tag ids. The transaction ends up with exactly these tags.
linesobject[]The full list of lines. A line with an
idkeeps that saved line; one without is added; a saved line left out is removed.accountIdstringSingle-line shorthand instead of
lines. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.amountMinorintegerSingle-line shorthand: the amount in pence (zero allowed). For a transfer, the amount moved.
categoryIdstringSingle-line shorthand: the category.
payeeIdstringSingle-line shorthand: the payee.
fromAccountIdstringTransfers only: where the money leaves. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.
toAccountIdstringTransfers only: where the money arrives. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.
versionstring | numberThe
versionfrom your last read, as an alternative to theIf-Matchheader.
Response fields
idstringrequiredThe transaction id.
datestringrequiredThe day it happened, YYYY-MM-DD in UK time.
atstringrequiredThe moment it happened, ISO 8601 in UTC.
descriptionstringrequiredWhat the transaction is called.
descriptionAutobooleanrequiredTrue when the app writes the description from the lines, and rewrites it when they change.
notesstring | nullrequiredFree-text notes.
kind"expense" | "income" | "transfer"requiredWhether money went out, came in, or moved between your own accounts.
isTransferbooleanrequiredTrue for a move between your own accounts.
Errors
validation_failed400The body is empty, a line
idis not one of this transaction's lines, orkindchanges withoutlines. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404A 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.
forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
transactions:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/transactions/txn_1 \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"description": "Weekly shop (Corner Market)",
"lines": [
{
"id": "line_1",
"amountMinor": 4350
}
]
}'{
"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"
}
}Set a transaction’s tags
/api/v1/transactions/{id}/tagsReplaces 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.
Path parameters
idstringrequiredThe transaction id.
Request body (JSON)
tagIdsstring[]requiredTag ids. The transaction ends up with exactly these tags.
versionstring | numberThe
versionfrom your last read, as an alternative to theIf-Matchheader.
Response fields
idstringrequiredThe transaction id.
datestringrequiredThe day it happened, YYYY-MM-DD in UK time.
atstringrequiredThe moment it happened, ISO 8601 in UTC.
descriptionstringrequiredWhat the transaction is called.
descriptionAutobooleanrequiredTrue when the app writes the description from the lines, and rewrites it when they change.
notesstring | nullrequiredFree-text notes.
kind"expense" | "income" | "transfer"requiredWhether money went out, came in, or moved between your own accounts.
isTransferbooleanrequiredTrue for a move between your own accounts.
Errors
validation_failed400A tag id in
tagIdsis not one of your tags. A body field is missing, wrong, or not one this endpoint knows;detailslists each.forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).not_found404Nothing exists with that id, or it belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
transactions:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PUT https://finance.jagwebsites.xyz/api/v1/transactions/txn_1/tags \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"tagIds": [
"tag_1",
"tag_2"
]
}'{
"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"
}
}Delete a transaction
/api/v1/transactions/{id}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.
Path parameters
idstringrequiredThe transaction id.
Query parameters
documents"keep" | "delete"keep(the default) leaves attached documents unfiled;deletemoves documents attached only to this transaction to the trash.
Errors
conflict409The transaction has linked refunds or chargebacks (
reason: has_linked_refunds), or is an account's opening balance (reason: opening_balance).forbidden_scope403documents=deleteis sent without thedocuments:deletescope. The key lacks thetransactions:deletescope;requiredScopenames it.forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).documents=deleteis sent by a key limited to some accounts (reason: account_limit).not_found404Nothing exists with that id, or it belongs to someone else.
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X DELETE 'https://finance.jagwebsites.xyz/api/v1/transactions/txn_1?documents=keep' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"'204 with no body.
Create many transactions at once
/api/v1/transactions/batchPosts 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.
Request body (JSON)
transactionsobject[]required1–100 transactions, each exactly the body of POST /transactions.
Response fields
idstringrequiredThe transaction id.
datestringrequiredThe day it happened, YYYY-MM-DD in UK time.
atstringrequiredThe moment it happened, ISO 8601 in UTC.
descriptionstringrequiredWhat the transaction is called.
descriptionAutobooleanrequiredTrue when the app writes the description from the lines, and rewrites it when they change.
notesstring | nullrequiredFree-text notes.
kind"expense" | "income" | "transfer"requiredWhether money went out, came in, or moved between your own accounts.
isTransferbooleanrequiredTrue for a move between your own accounts.
Errors
forbidden403The key is limited to some accounts and an item names another one; nothing is created and
detailsnames the item (reason: account_limit).validation_failed400A body field is missing, wrong, or not one this endpoint knows;
detailslists each.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
transactions:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/transactions/batch \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"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"
}
]
}'{
"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"
}
]
}Export transactions as CSV
/api/v1/transactions/exportA 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.
Query parameters
fromstringEarliest date, inclusive.
YYYY-MM-DD(a whole UK day) or an ISO 8601 timestamp.tostringLatest date, inclusive.
YYYY-MM-DDruns to the end of that UK day; a timestamp is that instant.accountIdstringA payment source (card, pot or account activity) id, or a financial account id for all of its sources.
categoryIdstringOnly transactions with a line in this category or any category under it (a parent category includes its subcategories, as on the Transactions page).
payeeIdstringOnly transactions with a line for this payee or any payee under it (a parent payee includes its sub-payees).
tagIdstringOnly transactions carrying this tag.
kind"expense" | "income" | "transfer"Expense, income or transfer, read from all of a transaction’s lines as the app does.
minAmountMinorintegerSmallest absolute amount in pence, up to 2147483647.
maxAmountMinorintegerLargest absolute amount in pence, up to 2147483647.
qstringText search over the description, notes and item names, with the same AND / OR / NOT, "quotes" and accent folding as the Transactions page.
hasDocuments"0" | "1" | "true" | "false"truefor transactions with documents attached,falsefor those without. Needs thedocuments:readscope and a key for all accounts.format"csv"The file format. Only
csvfor now.
Errors
validation_failed400More lines match than one file holds; narrow the dates. A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403hasDocumentsis used without thedocuments:readscope. The key lacks thetransactions:readscope;requiredScopenames it.forbidden403hasDocumentsorinclude=documentsis used by a key limited to some accounts (reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/transactions/export?from=2026-10-01&to=2026-10-31' \
-H 'Authorization: Bearer sk_your_key'date,transactionId,description,kind,account,category,payee,tags,amount,amountMinor,currency,notes
2026-10-24,txn_1,Weekly shop,expense,Everyday card,Groceries,Corner Market,Household,-42.10,-4210,GBP,
2026-10-23,txn_2,"Lunch, with Sam",expense,Everyday card,Eating out,Cafe Nero,,-8.40,-840,GBP,Split the bill
Categories
5 endpoints
List categories
/api/v1/categoriesEvery 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.
Query parameters
archived"exclude" | "include" | "only"Archived items:
exclude(default),includeoronly. WithupdatedSincethe default isinclude, so a change to archived shows.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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).
Response fields
idstringrequiredThe category id.
namestringrequiredThe category name.
parentIdstring | nullrequiredThe parent category, for a category inside a group; null at the top.
systemKeystring | nullrequiredSet on the categories the app itself relies on, such as starting balance.
iconstring | nullrequiredThe icon name, if one is set.
colorstring | nullrequiredThe colour as a hex code, if one is set.
notesstring | nullrequiredFree-text notes about what belongs in this category; null when none are set.
sortOrderintegerrequiredPosition among its siblings; lower comes first.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
categories:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/categories?archived=exclude' \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Get a category
/api/v1/categories/{id}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.
Path parameters
idstringrequiredThe category id.
Response fields
idstringrequiredThe category id.
namestringrequiredThe category name.
parentIdstring | nullrequiredThe parent category, for a category inside a group; null at the top.
systemKeystring | nullrequiredSet on the categories the app itself relies on, such as starting balance.
iconstring | nullrequiredThe icon name, if one is set.
colorstring | nullrequiredThe colour as a hex code, if one is set.
notesstring | nullrequiredFree-text notes about what belongs in this category; null when none are set.
sortOrderintegerrequiredPosition among its siblings; lower comes first.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
categories:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/categories/cat_1 \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}List categorisation rules
/api/v1/rulesThe 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.
Query parameters
archived"exclude" | "include" | "only"Archived items:
exclude(default),includeoronly. WithupdatedSincethe default isinclude, so a change to archived shows.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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).
Response fields
idstringrequiredThe rule id.
namestringrequiredThe rule name.
priorityintegerrequiredHigher numbers win when two rules set the same field.
enabledbooleanrequiredFalse while the rule is switched off.
applyMode"suggest" | "auto_apply" | nullrequiredNull follows the default in Settings.
autoApproveTrustedbooleanrequiredWhether the rule also approves matching items it trusts without asking.
matchDescriptionstringrequiredThe conditions in words, as the Rules page shows them.
payeeobject | nullrequiredThe payee the rule matches, or null when it does not match on payee.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
categories:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/rules?archived=exclude' \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Create a category
/api/v1/categoriesCreates a category, optionally inside another one. Answers 409 conflict when a category with that name already exists under the same parent.
Request body (JSON)
namestringrequiredThe category name. Names are unique among categories with the same parent.
parentIdstring | nullThe category to nest it under. Omit or null for a top-level category.
icon"store" | "building" | "user" | "globe" | "shopping-cart" | "coffee" | "utensils" | "home" | "car" | "train" | "heart" | "briefcase" | "gift" | "wallet" | "tag" | nullAn 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.
colorstring | nullA six-digit hex colour such as
#cc2936. Null clears it.notesstring | nullFree-text notes about what belongs in this category. Null or blank clears them.
Response fields
idstringrequiredThe category id.
namestringrequiredThe category name.
parentIdstring | nullrequiredThe parent category, for a category inside a group; null at the top.
systemKeystring | nullrequiredSet on the categories the app itself relies on, such as starting balance.
iconstring | nullrequiredThe icon name, if one is set.
colorstring | nullrequiredThe colour as a hex code, if one is set.
notesstring | nullrequiredFree-text notes about what belongs in this category; null when none are set.
sortOrderintegerrequiredPosition among its siblings; lower comes first.
Errors
conflict409A category with that name already exists under the same parent.
not_found404The
parentIddoes not exist or belongs to someone else.validation_failed400A body field is missing, wrong, or not one this endpoint knows;
detailslists each.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
categories:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/categories \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"name": "Groceries",
"parentId": "cat_0",
"icon": "shopping-cart",
"color": "#cc2936"
}'{
"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"
}
}Edit or archive a category
/api/v1/categories/{id}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.
Path parameters
idstringrequiredThe category id.
Request body (JSON)
namestringA new name.
parentIdstring | nullMove under this category, or null to make it top-level.
icon"store" | "building" | "user" | "globe" | "shopping-cart" | "coffee" | "utensils" | "home" | "car" | "train" | "heart" | "briefcase" | "gift" | "wallet" | "tag" | nullAn 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.
colorstring | nullA six-digit hex colour such as
#cc2936. Null clears it.notesstring | nullFree-text notes about what belongs in this category. Null or blank clears them.
archivedbooleanTrue archives the category and every category inside it; false restores just this one.
versionstringThe
versionyou last read, as an alternative to theIf-Matchheader.
Response fields
idstringrequiredThe category id.
namestringrequiredThe category name.
parentIdstring | nullrequiredThe parent category, for a category inside a group; null at the top.
systemKeystring | nullrequiredSet on the categories the app itself relies on, such as starting balance.
iconstring | nullrequiredThe icon name, if one is set.
colorstring | nullrequiredThe colour as a hex code, if one is set.
notesstring | nullrequiredFree-text notes about what belongs in this category; null when none are set.
sortOrderintegerrequiredPosition among its siblings; lower comes first.
Errors
validation_failed400The body is empty, or a system category is being archived. A body field is missing, wrong, or not one this endpoint knows;
detailslists each.conflict409Another category under the same parent already has that name.
not_found404The
parentIddoes not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
categories:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/categories/cat_1 \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"name": "Food shopping",
"archived": false
}'{
"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"
}
}Payees
4 endpoints
List payees
/api/v1/payeesPayees 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.
Query parameters
archived"exclude" | "include" | "only"Archived items:
exclude(default),includeoronly. WithupdatedSincethe default isinclude, so a change to archived shows.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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).qstringOnly payees whose name contains this text.
limitintegerPayees per page, 1–200 (50 by default).
cursorstringpage.nextCursorfrom the previous page.
Response fields
idstringrequiredThe payee id.
namestringrequiredThe payee name.
kind"general" | "physical" | "online"requiredgeneralfor any payee,physicalfor a shop with locations,onlinefor a web shop.transactionType"expense" | "income" | "both"requiredWhat the payee is used for.
parentobject | nullrequiredThe payee this one is a branch of.
parent.idstringrequiredIts id.
parent.namestringrequiredIts name.
defaultCategoryobject | nullrequiredThe category new transactions with this payee start with, or null.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
payees:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/payees?q=market&limit=20' \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Get a payee
/api/v1/payees/{id}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.
Path parameters
idstringrequiredThe payee id.
Response fields
idstringrequiredThe payee id.
namestringrequiredThe payee name.
kind"general" | "physical" | "online"requiredgeneralfor any payee,physicalfor a shop with locations,onlinefor a web shop.transactionType"expense" | "income" | "both"requiredWhat the payee is used for.
parentobject | nullrequiredThe payee this one is a branch of.
parent.idstringrequiredIts id.
parent.namestringrequiredIts name.
defaultCategoryobject | nullrequiredThe category new transactions with this payee start with, or null.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
payees:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/payees/pay_1 \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Create a payee
/api/v1/payeesCreates a payee. transactionType defaults to both. Answers 409 conflict when a payee with that name already exists under the same parent.
Request body (JSON)
namestringrequiredThe payee name. Names are unique among payees with the same parent.
kind"general" | "physical" | "online"general(the default),physical(a shop or branch) oronline.transactionType"expense" | "income" | "both"What the payee is used for. Defaults to
bothwhen creating.parentIdstring | nullThe payee this one is a branch of. Null makes it top-level.
defaultCategoryIdstring | nullThe category new transactions for this payee start with. Null clears it.
icon"store" | "building" | "user" | "globe" | "shopping-cart" | "coffee" | "utensils" | "home" | "car" | "train" | "heart" | "briefcase" | "gift" | "wallet" | "tag" | nullAn icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag.
colorstring | nullA six-digit hex colour such as
#cc2936.websiteUrlstring | nullAn https:// address without credentials.
notesstring | nullFree text.
Response fields
idstringrequiredThe payee id.
namestringrequiredThe payee name.
kind"general" | "physical" | "online"requiredgeneralfor any payee,physicalfor a shop with locations,onlinefor a web shop.transactionType"expense" | "income" | "both"requiredWhat the payee is used for.
parentobject | nullrequiredThe payee this one is a branch of.
parent.idstringrequiredIts id.
parent.namestringrequiredIts name.
defaultCategoryobject | nullrequiredThe category new transactions with this payee start with, or null.
Errors
conflict409A payee with that name already exists under the same parent.
not_found404The
parentIdordefaultCategoryIddoes not exist or belongs to someone else.validation_failed400A body field is missing, wrong, or not one this endpoint knows;
detailslists each.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
payees:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/payees \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"name": "Corner Market",
"kind": "physical",
"transactionType": "expense",
"defaultCategoryId": "cat_1"
}'{
"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"
}
}Edit, archive or restore a payee
/api/v1/payees/{id}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.
Path parameters
idstringrequiredThe payee id.
Request body (JSON)
namestringA new name.
kind"general" | "physical" | "online"general(the default),physical(a shop or branch) oronline.transactionType"expense" | "income" | "both"What the payee is used for. Defaults to
bothwhen creating.parentIdstring | nullThe payee this one is a branch of. Null makes it top-level.
defaultCategoryIdstring | nullThe category new transactions for this payee start with. Null clears it.
icon"store" | "building" | "user" | "globe" | "shopping-cart" | "coffee" | "utensils" | "home" | "car" | "train" | "heart" | "briefcase" | "gift" | "wallet" | "tag" | nullAn icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag.
colorstring | nullA six-digit hex colour such as
#cc2936.websiteUrlstring | nullAn https:// address without credentials.
notesstring | nullFree text.
archivedbooleanTrue archives the payee (its sub-payees must be archived first); false restores it.
versionstringThe
versionyou last read, as an alternative to theIf-Matchheader.
Response fields
idstringrequiredThe payee id.
namestringrequiredThe payee name.
kind"general" | "physical" | "online"requiredgeneralfor any payee,physicalfor a shop with locations,onlinefor a web shop.transactionType"expense" | "income" | "both"requiredWhat the payee is used for.
parentobject | nullrequiredThe payee this one is a branch of.
parent.idstringrequiredIts id.
parent.namestringrequiredIts name.
defaultCategoryobject | nullrequiredThe category new transactions with this payee start with, or null.
Errors
validation_failed400The 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;
detailslists each.conflict409Another payee under the same parent has that name, or
kindchanges on a payee that already has transactions.not_found404The
parentIdordefaultCategoryIddoes not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
payees:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/payees/pay_1 \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"name": "Corner Market Ltd",
"archived": false
}'{
"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"
}
}Bills
15 endpoints
What is due soon
/api/v1/bills/upcomingRecurring 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).
Query parameters
daysintegerHow many days ahead to look, 1 to 366.
limitintegerItems per page, 1 to 200.
cursorstringThe
nextCursorof the previous page.
Response fields
type"recurring" | "scheduled"requiredrecurringfor an occurrence of a repeating bill,scheduledfor a one-off scheduled item.idstringrequiredThe occurrence id (recurring) or the scheduled item id.
seriesIdstring | nullrequiredThe recurring series it belongs to; null for a scheduled item.
namestringrequiredWhat the bill is called.
direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
dueOnstringrequiredThe day it is due, YYYY-MM-DD.
status"pending" | "pre_approved"requiredpendingwaits for you to post it;pre_approvedwill be posted on its day.accountobject | nullrequiredThe account the money leaves or arrives in, or null.
Errors
validation_failed400daysis outside 1 to 366, or thecursoris not one a previous page gave. A query parameter is wrong, or not one this endpoint knows;detailslists each.forbidden_scope403The key lacks the
bills:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/bills/upcoming?days=14' \
-H 'Authorization: Bearer sk_your_key'{
"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
}
}Recurring bills and income
/api/v1/recurringRecurring 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.
Query parameters
statusstringComma-separated: active, paused, ended, suggested, dismissed. Default
active,paused, or all of them withupdatedSince.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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).
Response fields
idstringrequiredThe series id.
namestringrequiredWhat the series is called.
status"active" | "paused" | "ended" | "suggested" | "dismissed"requiredWhether it is running:
active,paused,ended, orsuggested/dismissedfor ones spotted from your transactions.direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"requiredHow often it repeats.
anchorDayintegerrequiredWeekday (0 = Sunday) for weekly cadences, day of the month otherwise.
anchorMonthinteger | nullrequiredYearly series only.
intervalDaysinteger | nullrequiredCustom cadence only: every N days.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
bills:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/recurring \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}One recurring series
/api/v1/recurring/{id}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).
Path parameters
idstringrequiredThe id.
Response fields
idstringrequiredThe series id.
namestringrequiredWhat the series is called.
status"active" | "paused" | "ended" | "suggested" | "dismissed"requiredWhether it is running:
active,paused,ended, orsuggested/dismissedfor ones spotted from your transactions.direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"requiredHow often it repeats.
anchorDayintegerrequiredWeekday (0 = Sunday) for weekly cadences, day of the month otherwise.
anchorMonthinteger | nullrequiredYearly series only.
intervalDaysinteger | nullrequiredCustom cadence only: every N days.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
bills:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/recurring/ser_1 \
-H 'Authorization: Bearer sk_your_key'{
"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": []
}
}Scheduled one-off items
/api/v1/scheduledOne-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.
Query parameters
statusstringComma-separated: pending, pre_approved, posted, cancelled. Default
pending,pre_approved, or all of them withupdatedSince.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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).limitintegerItems per page, 1 to 200.
cursorstringThe
nextCursorof the previous page.
Response fields
idstringrequiredThe scheduled item id.
namestringrequiredWhat the item is called.
notesstring | nullrequiredFree-text notes.
direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
dueOnstringrequiredThe day it is due, YYYY-MM-DD.
status"pending" | "pre_approved" | "posted" | "cancelled"requiredWhere it has got to: waiting, pre-approved, posted as a transaction or cancelled.
accountobject | nullrequiredThe account the money leaves or arrives in, or null.
account.idstringrequiredThe payment source id.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
bills:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/scheduled \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}One scheduled item
/api/v1/scheduled/{id}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.
Path parameters
idstringrequiredThe id.
Response fields
idstringrequiredThe scheduled item id.
namestringrequiredWhat the item is called.
notesstring | nullrequiredFree-text notes.
direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
dueOnstringrequiredThe day it is due, YYYY-MM-DD.
status"pending" | "pre_approved" | "posted" | "cancelled"requiredWhere it has got to: waiting, pre-approved, posted as a transaction or cancelled.
accountobject | nullrequiredThe account the money leaves or arrives in, or null.
account.idstringrequiredThe payment source id.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
bills:readscope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/scheduled/sch_1 \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Schedule a one-off payment
/api/v1/scheduledSchedules 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.
Request body (JSON)
descriptionstringrequiredWhat it is, such as “Car service”. Becomes the transaction description when it posts.
dueOnstringrequiredThe day it is due.
YYYY-MM-DD.direction"expense" | "income" | "transfer"requiredexpenseis money out,incomemoney in,transferbetween two of your accounts.amountMinorintegerrequiredThe amount in pence, always positive;
directionsays which way it goes.accountIdstringrequiredThe account the money comes out of (or goes into, for income). A payment source id (the
accountof a bill), not a financial account id.counterAccountIdstringTransfers only, and required for them: the account the money goes into.
categoryIdstringThe category to post it under. Required for an expense or income; a transfer is filed under Transfer.
payeeIdstringThe payee to post it under.
notesstring | nullFree-text notes.
autoPostbooleanPost it to the ledger by itself on the due day (default false). If the due day is today or past, it posts straight away.
remindDaysBeforeintegerSend a reminder this many days before it is due, 0 to 30.
Response fields
idstringrequiredThe scheduled item id.
namestringrequiredWhat the item is called.
notesstring | nullrequiredFree-text notes.
direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
dueOnstringrequiredThe day it is due, YYYY-MM-DD.
status"pending" | "pre_approved" | "posted" | "cancelled"requiredWhere it has got to: waiting, pre-approved, posted as a transaction or cancelled.
accountobject | nullrequiredThe account the money leaves or arrives in, or null.
account.idstringrequiredThe payment source id.
Errors
validation_failed400A transfer has no
counterAccountId, or an expense or income has nocategoryId. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404An account, category or payee in the body does not exist or belongs to someone else.
forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/scheduled \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"description": "Car service",
"dueOn": "2026-11-14",
"direction": "expense",
"amountMinor": 18900,
"accountId": "src_1",
"categoryId": "cat_2",
"payeeId": "pay_2",
"remindDaysBefore": 3
}'{
"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"
}
}Change a scheduled item
/api/v1/scheduled/{id}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.
Path parameters
idstringrequiredThe id.
Request body (JSON)
descriptionstringA new description.
dueOnstringA new due day.
YYYY-MM-DD.amountMinorintegerA new amount in pence, always positive.
accountIdstringA new account. A payment source id (the
accountof a bill), not a financial account id.counterAccountIdstringTransfers only: a new account the money goes into.
categoryIdstring | nullA new category. Null clears it.
payeeIdstring | nullA new payee. Null clears it.
notesstring | nullNew notes. Null clears them.
autoPostbooleanTurn automatic posting on or off.
remindDaysBeforeintegerSend a reminder this many days before it is due, 0 to 30.
versionstring | integerThe
versionyou last read. The same as sendingIf-Match; if the item has changed since, the answer is 412.
Response fields
idstringrequiredThe scheduled item id.
namestringrequiredWhat the item is called.
notesstring | nullrequiredFree-text notes.
direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
dueOnstringrequiredThe day it is due, YYYY-MM-DD.
status"pending" | "pre_approved" | "posted" | "cancelled"requiredWhere it has got to: waiting, pre-approved, posted as a transaction or cancelled.
accountobject | nullrequiredThe account the money leaves or arrives in, or null.
account.idstringrequiredThe payment source id.
Errors
validation_failed400The body is empty, or the item is already posted or cancelled. A body field is missing, wrong, or not one this endpoint knows;
detailslists each.conflict409The item is split across several lines (
reason: multiple_lines), so it cannot be changed field by field.not_found404An 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.
forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/scheduled/sch_1 \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"dueOn": "2026-11-20",
"amountMinor": 20500
}'{
"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"
}
}Post a scheduled item to the ledger
/api/v1/scheduled/{id}/postPosts 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.
Path parameters
idstringrequiredThe id.
Request body (JSON)
datestringThe transaction date to post it under (default: the day it was scheduled for).
YYYY-MM-DD.amountMinorintegerPost a different amount (in pence, positive) than the one scheduled.
Response fields
idstringrequiredThe scheduled item id.
namestringrequiredWhat the item is called.
notesstring | nullrequiredFree-text notes.
direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
dueOnstringrequiredThe day it is due, YYYY-MM-DD.
status"pending" | "pre_approved" | "posted" | "cancelled"requiredWhere it has got to: waiting, pre-approved, posted as a transaction or cancelled.
accountobject | nullrequiredThe account the money leaves or arrives in, or null.
account.idstringrequiredThe payment source id.
Errors
validation_failed400The item is already posted or cancelled. A body field is missing, wrong, or not one this endpoint knows;
detailslists each.conflict409amountMinoris sent for an item with several lines (reason: multiple_lines); post it as scheduled, or change it in the app.not_found404Nothing exists with that id, or it belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/scheduled/sch_1/post \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"date": "2026-11-14",
"amountMinor": 18900
}'{
"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"
}
}Cancel a scheduled item
/api/v1/scheduled/{id}/cancelCancels 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.
Path parameters
idstringrequiredThe id.
Response fields
idstringrequiredThe scheduled item id.
namestringrequiredWhat the item is called.
notesstring | nullrequiredFree-text notes.
direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
dueOnstringrequiredThe day it is due, YYYY-MM-DD.
status"pending" | "pre_approved" | "posted" | "cancelled"requiredWhere it has got to: waiting, pre-approved, posted as a transaction or cancelled.
accountobject | nullrequiredThe account the money leaves or arrives in, or null.
account.idstringrequiredThe payment source id.
Errors
validation_failed400The item has already been posted.
not_found404Nothing exists with that id, or it belongs to someone else.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:deletescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/scheduled/sch_1/cancel \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11'{
"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"
}
}Create a recurring bill or income
/api/v1/recurringCreates 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.
Request body (JSON)
namestringrequiredWhat it is, such as “Broadband”.
direction"expense" | "income" | "transfer"expense(the default),incomeortransfer.cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"requiredHow often it repeats.
anchorDayintegerWeekday (0 = Sunday to 6) for weekly, fortnightly and four-weekly cadences; day of the month (1 to 31) for the rest. Worked out from
startOnwhen left out.anchorMonthinteger | nullYearly cadence only: the month, 1 to 12. Worked out from
startOnwhen left out.intervalDaysinteger | nullCustom cadence only, and required for it: repeat every this many days.
startOnstringThe first day it can fall due (default today). Its first due day is the first one on or after this.
YYYY-MM-DD.expectedAmountMinorintegerrequiredThe usual amount of one payment, in pence, always positive.
accountIdstringrequiredThe account it is paid from (or into, for income). A payment source id (the
accountof a bill), not a financial account id.counterAccountIdstringTransfers only, and required for them: the account the money goes into.
categoryIdstringThe category payments are posted under. Required for an expense or income; a transfer is filed under Transfer.
payeeIdstringThe payee payments are posted under. Needed before an occurrence can be posted.
remindDaysBeforeintegerRemind this many days before each is due, 0 to 30 (default 3).
notesstring | nullFree-text notes.
Response fields
idstringrequiredThe series id.
namestringrequiredWhat the series is called.
status"active" | "paused" | "ended" | "suggested" | "dismissed"requiredWhether it is running:
active,paused,ended, orsuggested/dismissedfor ones spotted from your transactions.direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"requiredHow often it repeats.
anchorDayintegerrequiredWeekday (0 = Sunday) for weekly cadences, day of the month otherwise.
anchorMonthinteger | nullrequiredYearly series only.
intervalDaysinteger | nullrequiredCustom cadence only: every N days.
Errors
validation_failed400A custom cadence has no
intervalDays, a transfer has nocounterAccountId, or an expense or income has nocategoryId. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404An account, category or payee in the body does not exist or belongs to someone else.
forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/recurring \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"name": "Broadband",
"cadence": "monthly",
"startOn": "2026-11-02",
"expectedAmountMinor": 3299,
"accountId": "src_1",
"categoryId": "cat_1",
"payeeId": "pay_1"
}'{
"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": []
}
}Change a recurring series
/api/v1/recurring/{id}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.
Path parameters
idstringrequiredThe id.
Request body (JSON)
namestringA new name.
direction"expense" | "income" | "transfer"A new direction. Not allowed while customised or pre-approved payments are still to come.
cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"A new cadence. Open, uncustomised future occurrences are regenerated; customised or pre-approved ones block it (409-style 400).
anchorDayintegerWeekday (0 = Sunday to 6) for weekly, fortnightly and four-weekly cadences; day of the month (1 to 31) for the rest. Worked out from
startOnwhen left out.anchorMonthinteger | nullYearly cadence only: the month, 1 to 12. Worked out from
startOnwhen left out.intervalDaysinteger | nullCustom cadence only, and required for it: repeat every this many days.
expectedAmountMinorintegerA new usual amount in pence, always positive. Applies to occurrences not yet customised.
accountIdstringA new account. A payment source id (the
accountof a bill), not a financial account id.counterAccountIdstring | nullTransfers only: a new account the money goes into.
categoryIdstring | nullA new default category. Null clears it.
payeeIdstring | nullA new default payee. Null clears it.
remindDaysBeforeintegerSend a reminder this many days before it is due, 0 to 30.
notesstring | nullNew notes. Null clears them.
versionstring | integerThe
versionyou last read. The same as sendingIf-Match; if the item has changed since, the answer is 412.
Response fields
idstringrequiredThe series id.
namestringrequiredWhat the series is called.
status"active" | "paused" | "ended" | "suggested" | "dismissed"requiredWhether it is running:
active,paused,ended, orsuggested/dismissedfor ones spotted from your transactions.direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"requiredHow often it repeats.
anchorDayintegerrequiredWeekday (0 = Sunday) for weekly cadences, day of the month otherwise.
anchorMonthinteger | nullrequiredYearly series only.
intervalDaysinteger | nullrequiredCustom cadence only: every N days.
Errors
validation_failed400The 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;
detailslists each.not_found404An 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.
forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/recurring/ser_1 \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"expectedAmountMinor": 3499
}'{
"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": []
}
}Pause a recurring series
/api/v1/recurring/{id}/pauseStops 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.
Path parameters
idstringrequiredThe id.
Response fields
idstringrequiredThe series id.
namestringrequiredWhat the series is called.
status"active" | "paused" | "ended" | "suggested" | "dismissed"requiredWhether it is running:
active,paused,ended, orsuggested/dismissedfor ones spotted from your transactions.direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"requiredHow often it repeats.
anchorDayintegerrequiredWeekday (0 = Sunday) for weekly cadences, day of the month otherwise.
anchorMonthinteger | nullrequiredYearly series only.
intervalDaysinteger | nullrequiredCustom cadence only: every N days.
Errors
conflict409Only an active series can be paused (
reason: series_not_active).not_found404Nothing exists with that id, or it belongs to someone else.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/recurring/ser_1/pause \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11'{
"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": []
}
}Resume a recurring series
/api/v1/recurring/{id}/resumeMakes 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.
Path parameters
idstringrequiredThe id.
Request body (JSON)
catchUpDueOnsstring[]Missed due days to bring back as pending occurrences. They must fall in the missed window; none by default.
Response fields
idstringrequiredThe series id.
namestringrequiredWhat the series is called.
status"active" | "paused" | "ended" | "suggested" | "dismissed"requiredWhether it is running:
active,paused,ended, orsuggested/dismissedfor ones spotted from your transactions.direction"expense" | "income" | "transfer"requiredWhether money goes out, comes in or moves between your own accounts.
cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"requiredHow often it repeats.
anchorDayintegerrequiredWeekday (0 = Sunday) for weekly cadences, day of the month otherwise.
anchorMonthinteger | nullrequiredYearly series only.
intervalDaysinteger | nullrequiredCustom cadence only: every N days.
Errors
conflict409Only a paused or ended series can be resumed (
reason: series_not_paused).validation_failed400A day in
catchUpDueOnsis not aYYYY-MM-DDday. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404Nothing exists with that id, or it belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/recurring/ser_1/resume \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{}'{
"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": []
}
}Post a recurring occurrence to the ledger
/api/v1/recurring/{id}/occurrences/{dueOn}/postPosts 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.
Path parameters
idstringrequiredThe recurring series id.
dueOnstringrequiredThe occurrence’s due day,
YYYY-MM-DD, asdueOnin the series’ occurrences.
Request body (JSON)
datestringThe transaction date to post it under (default: its due day).
YYYY-MM-DD.amountMinorintegerPost a different amount (in pence, positive) than planned.
Response fields
idstringrequiredThe occurrence id.
dueOnstringrequiredThe day it is due, YYYY-MM-DD.
status"pending" | "pre_approved" | "posted" | "skipped" | "cancelled"requiredWhere it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled.
descriptionstringrequiredWhat the transaction will be called.
transactionIdstring | nullrequiredThe ledger transaction it was posted as. Always null unless the key can read transactions.
postedAtstring | nullrequiredWhen it was posted, ISO 8601 in UTC; null until then.
amountMinorintegerrequiredAmount, in whole pence.
amountDisplaystringrequiredAmount, ready to show, such as £12.50.
seriesIdstringrequiredThe series it belongs to.
Errors
validation_failed400The 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;detailslists each.conflict409amountMinoris sent for an occurrence with several lines (reason: multiple_lines).not_found404The series has no occurrence due on that day. Nothing exists with that id, or it belongs to someone else.
forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/recurring/ser_1/occurrences/2026-11-02/post \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"amountMinor": 3299
}'{
"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"
}
}Skip a recurring occurrence
/api/v1/recurring/{id}/occurrences/{dueOn}/skipMarks 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.
Path parameters
idstringrequiredThe recurring series id.
dueOnstringrequiredThe occurrence’s due day,
YYYY-MM-DD, asdueOnin the series’ occurrences.
Response fields
idstringrequiredThe occurrence id.
dueOnstringrequiredThe day it is due, YYYY-MM-DD.
status"pending" | "pre_approved" | "posted" | "skipped" | "cancelled"requiredWhere it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled.
descriptionstringrequiredWhat the transaction will be called.
transactionIdstring | nullrequiredThe ledger transaction it was posted as. Always null unless the key can read transactions.
postedAtstring | nullrequiredWhen it was posted, ISO 8601 in UTC; null until then.
amountMinorintegerrequiredAmount, in whole pence.
amountDisplaystringrequiredAmount, ready to show, such as £12.50.
seriesIdstringrequiredThe series it belongs to.
Errors
validation_failed400Only a pending or pre-approved occurrence can be skipped.
not_found404The series has no occurrence due on that day. Nothing exists with that id, or it belongs to someone else.
forbidden403The key is limited to some accounts and this would involve another one (
reason: account_limit).idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
bills:writescope;requiredScopenames it.unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/recurring/ser_1/occurrences/2026-11-02/skip \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11'{
"data": {
"id": "occ_1",
"seriesId": "ser_1",
"dueOn": "2026-11-02",
"status": "skipped",
"description": "Broadband",
"amountMinor": 3299,
"amountDisplay": "£32.99",
"transactionId": null,
"postedAt": null
}
}Budgets
5 endpoints
List budgets for a month
/api/v1/budgetsEvery 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.
Query parameters
monthstringThe month to show,
YYYY-MM. Defaults to the current UK month.archived"exclude" | "include" | "only"Archived items:
exclude(default),includeoronly. WithupdatedSincethe default isinclude, so a change to archived shows.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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).
Response fields
idstringrequiredThe budget id.
namestringrequiredThe budget name.
scope"category" | "account" | "envelope"requiredWhat it watches: a
category, anaccountor anenvelopeof money set aside.categoryobject | nullrequiredThe category (and its subcategories) this budget watches.
category.idstringrequiredIts id.
category.namestringrequiredIts name.
accountobject | nullrequiredThe financial account this budget is limited to.
account.idstringrequiredIts id.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
budgets:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/budgets?month=2026-10' \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Get a budget
/api/v1/budgets/{id}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.
Path parameters
idstringrequiredThe budget id.
Query parameters
monthstringThe month to show,
YYYY-MM. Defaults to the current UK month.
Response fields
idstringrequiredThe budget id.
namestringrequiredThe budget name.
scope"category" | "account" | "envelope"requiredWhat it watches: a
category, anaccountor anenvelopeof money set aside.categoryobject | nullrequiredThe category (and its subcategories) this budget watches.
category.idstringrequiredIts id.
category.namestringrequiredIts name.
accountobject | nullrequiredThe financial account this budget is limited to.
account.idstringrequiredIts id.
Errors
not_found404The budget had not started by the requested
month. Nothing exists with that id, or it belongs to someone else.validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
budgets:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/budgets/bud_groceries?month=2026-10' \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
]
}
}Create a budget
/api/v1/budgetsCreates 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.
Request body (JSON)
namestringrequiredThe budget name.
scope"category" | "account" | "envelope"requiredcategorywatches one category and its subcategories,accountone financial account,envelopeis money you put aside and draw on.categoryIdstring | nullRequired for a
categorybudget.accountIdstring | nullThe financial account, required for an
accountbudget.rolloverMode"none" | "carry" | "buffer"Defaults to
none.alertThresholdPercentinteger | nullPercentage of the budget at which to warn you, 1–100. Null for no warning.
monthstringThe month the first allocation is for,
YYYY-MM. Defaults to the current UK month.plannedMinorintegerThe first month's allocation in pence. Leave out to set it later with
PUT /budgets/{id}/months/{month}.
Response fields
idstringrequiredThe budget id.
namestringrequiredThe budget name.
scope"category" | "account" | "envelope"requiredWhat it watches: a
category, anaccountor anenvelopeof money set aside.categoryobject | nullrequiredThe category (and its subcategories) this budget watches.
category.idstringrequiredIts id.
category.namestringrequiredIts name.
accountobject | nullrequiredThe financial account this budget is limited to.
account.idstringrequiredIts id.
Errors
validation_failed400Budgets are not switched on, a
categorybudget has nocategoryId, or anaccountbudget has noaccountId. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404The category or account does not exist or belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
budgets:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/budgets \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"name": "Groceries",
"scope": "category",
"categoryId": "cat_groceries",
"rolloverMode": "none",
"alertThresholdPercent": 75,
"month": "2026-10",
"plannedMinor": 40000
}'{
"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": []
}
}Edit or archive a budget
/api/v1/budgets/{id}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.
Path parameters
idstringrequiredThe budget id.
Request body (JSON)
namestringA new name.
categoryIdstring | nullWatch a different category (category budgets).
accountIdstring | nullWatch a different financial account (account budgets).
rolloverMode"none" | "carry" | "buffer"What happens to money left over:
none(it resets),carry(it rolls into next month) orbuffer(it builds a buffer).alertThresholdPercentinteger | nullPercentage of the budget at which to warn you, 1–100. Null for no warning.
archivedbooleanTrue archives the budget. A budget cannot be restored once archived:
falseon an archived budget answers 409.monthstringThe month to show in the answer,
YYYY-MM. Defaults to the current UK month.versionstringThe
versionyou last read, as an alternative to theIf-Matchheader.
Response fields
idstringrequiredThe budget id.
namestringrequiredThe budget name.
scope"category" | "account" | "envelope"requiredWhat it watches: a
category, anaccountor anenvelopeof money set aside.categoryobject | nullrequiredThe category (and its subcategories) this budget watches.
category.idstringrequiredIts id.
category.namestringrequiredIts name.
accountobject | nullrequiredThe financial account this budget is limited to.
account.idstringrequiredIts id.
Errors
validation_failed400The body is empty, the
scopeis changed, or the rollover mode changes once the budget has buffer draws. A body field is missing, wrong, or not one this endpoint knows;detailslists each.conflict409The budget is archived, so it cannot be edited or restored (
reason: budget_archived).not_found404Nothing exists with that id, or it belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
budgets:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/budgets/bud_groceries \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"name": "Food shopping",
"alertThresholdPercent": 80
}'{
"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": []
}
}Set a budget's allocation for a month
/api/v1/budgets/{id}/months/{month}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.
Path parameters
idstringrequiredThe budget id.
monthstringrequiredThe month,
YYYY-MM.
Request body (JSON)
amountMinorintegerrequiredThe month's allocation in pence.
versionstringThe budget
versionyou last read, as an alternative to theIf-Matchheader.
Response fields
idstringrequiredThe budget id.
namestringrequiredThe budget name.
scope"category" | "account" | "envelope"requiredWhat it watches: a
category, anaccountor anenvelopeof money set aside.categoryobject | nullrequiredThe category (and its subcategories) this budget watches.
category.idstringrequiredIts id.
category.namestringrequiredIts name.
accountobject | nullrequiredThe financial account this budget is limited to.
account.idstringrequiredIts id.
Errors
conflict409The budget is archived (
reason: budget_archived).not_found404Nothing exists with that id, or it belongs to someone else.
validation_failed400A body field is missing, wrong, or not one this endpoint knows;
detailslists each.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
budgets:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PUT https://finance.jagwebsites.xyz/api/v1/budgets/bud_groceries/months/2026-11 \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"amountMinor": 42500
}'{
"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": []
}
}Goals
5 endpoints
List goals
/api/v1/goalsSavings 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.
Query parameters
archived"exclude" | "include" | "only"Archived items:
exclude(default),includeoronly. WithupdatedSincethe default isinclude, so a change to archived shows.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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).
Response fields
idstringrequiredThe goal id.
namestringrequiredThe goal name.
type"savings" | "payoff"requiredsavingsbuilds towards a target;payoffclears a debt.progressPercentintegerrequiredProgress as a whole percentage of the target.
deadlinestring | nullrequiredCalendar day, YYYY-MM-DD.
deadlineStatus"none" | "future" | "due" | "overdue" | "met"requiredHow the deadline stands:
nonewhen there is no deadline,future,duetoday,overdue, ormetonce the target is reached.remainingDaysinteger | nullrequiredDays to the deadline; negative once it has passed.
accountobjectrequiredThe account the goal is measured on.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
goals:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/goals \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Get a goal
/api/v1/goals/{id}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.
Path parameters
idstringrequiredThe goal id.
Response fields
idstringrequiredThe goal id.
namestringrequiredThe goal name.
type"savings" | "payoff"requiredsavingsbuilds towards a target;payoffclears a debt.progressPercentintegerrequiredProgress as a whole percentage of the target.
deadlinestring | nullrequiredCalendar day, YYYY-MM-DD.
deadlineStatus"none" | "future" | "due" | "overdue" | "met"requiredHow the deadline stands:
nonewhen there is no deadline,future,duetoday,overdue, ormetonce the target is reached.remainingDaysinteger | nullrequiredDays to the deadline; negative once it has passed.
accountobjectrequiredThe account the goal is measured on.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
goals:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/goals/goal_holiday \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
]
}
}Create a goal
/api/v1/goalsCreates 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.
Request body (JSON)
namestringrequiredThe goal name.
type"savings" | "payoff"requiredsavingssets cash aside in a cash or savings account;payoffrepays the debt on a credit account.targetMinorintegerrequiredThe target in pence. For a payoff goal it cannot exceed the debt now.
deadlinestring | nullThe day to reach the target by,
YYYY-MM-DD. Null for no deadline.accountIdstringrequiredThe account the goal is measured on: where savings are held, or the credit account to pay off.
fundingAccountIdstring | nullFor a payoff goal, the cash account its reserved money comes from.
Response fields
idstringrequiredThe goal id.
namestringrequiredThe goal name.
type"savings" | "payoff"requiredsavingsbuilds towards a target;payoffclears a debt.progressPercentintegerrequiredProgress as a whole percentage of the target.
deadlinestring | nullrequiredCalendar day, YYYY-MM-DD.
deadlineStatus"none" | "future" | "due" | "overdue" | "met"requiredHow the deadline stands:
nonewhen there is no deadline,future,duetoday,overdue, ormetonce the target is reached.remainingDaysinteger | nullrequiredDays to the deadline; negative once it has passed.
accountobjectrequiredThe account the goal is measured on.
Errors
validation_failed400A 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;
detailslists each.not_found404The account or funding account does not exist or belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
goals:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/goals \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"name": "Summer holiday",
"type": "savings",
"targetMinor": 150000,
"deadline": "2027-03-01",
"accountId": "acc_savings"
}'{
"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": []
}
}Edit, archive or restore a goal
/api/v1/goals/{id}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.
Path parameters
idstringrequiredThe goal id.
Request body (JSON)
namestringA new name.
type"savings" | "payoff"Changing the type needs the goal to have no reserved funds.
targetMinorintegerA new target in pence; it cannot be below what is reserved.
deadlinestring | nullThe day to reach the target by,
YYYY-MM-DD. Null for no deadline.accountIdstringMeasure on a different account; needs no reserved funds.
fundingAccountIdstring | nullA payoff goal's funding account.
archivedbooleanTrue archives the goal; false restores it (the account must cover its reserve).
versionstringThe
versionyou last read, as an alternative to theIf-Matchheader.
Response fields
idstringrequiredThe goal id.
namestringrequiredThe goal name.
type"savings" | "payoff"requiredsavingsbuilds towards a target;payoffclears a debt.progressPercentintegerrequiredProgress as a whole percentage of the target.
deadlinestring | nullrequiredCalendar day, YYYY-MM-DD.
deadlineStatus"none" | "future" | "due" | "overdue" | "met"requiredHow the deadline stands:
nonewhen there is no deadline,future,duetoday,overdue, ormetonce the target is reached.remainingDaysinteger | nullrequiredDays to the deadline; negative once it has passed.
accountobjectrequiredThe account the goal is measured on.
Errors
validation_failed400The 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;
detailslists each.not_found404The account or funding account does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
goals:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/goals/goal_holiday \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"targetMinor": 180000,
"deadline": "2027-04-01"
}'{
"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": []
}
}Reserve or release money for a goal
/api/v1/goals/{id}/fundingAdds 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.
Path parameters
idstringrequiredThe goal id.
Request body (JSON)
amountMinorintegerrequiredPence to reserve (positive) or release (negative).
datestringrequiredThe day the money was set aside,
YYYY-MM-DD, today or earlier.notestring | nullA short note shown in the goal's history.
Response fields
idstringrequiredThe funding entry id.
occurredOnstringrequiredThe day the money was put towards the goal, YYYY-MM-DD.
notestring | nullrequiredA short note.
createdAtstring | nullrequiredWhen it was created, ISO 8601 in UTC.
amountMinorintegerrequiredThe amount put towards the goal, in whole pence.
amountDisplaystringrequiredThe amount put towards the goal, ready to show, such as £12.50.
goalobjectrequiredThe goal after the change.
goal.idstringrequiredThe goal id.
Errors
validation_failed400The funding account lacks enough unreserved cash, the reserve would pass the target or drop below zero, the goal is archived, or
dateis in the future. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404Nothing exists with that id, or it belongs to someone else.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
goals:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/goals/goal_holiday/funding \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"amountMinor": 25000,
"date": "2026-10-24",
"note": "From the bonus"
}'{
"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"
}
}
}Documents
15 endpoints
Add a payslip to a payment
/api/v1/connection/payslipsUploads 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).
Query parameters
transactionIdstringrequiredThe payment (income) to attach the payslip to.
Response fields
status"added" | "existing"requiredaddedfor a new document;existingwhen the same file was already one.documentIdstringrequiredThe payslip.
transactionIdstringrequiredThe payment it is attached to.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
documents:uploadscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST 'https://finance.jagwebsites.xyz/api/v1/connection/payslips?transactionId=txn_1' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11'{
"data": {
"status": "added",
"documentId": "doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91",
"transactionId": "txn_1"
}
}List documents
/api/v1/documentsYour 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.
Query parameters
tab"all" | "unfiled" | "review" | "trash"all(default),unfiled(attached to nothing),review(waiting in the Documents inbox) ortrash. WithupdatedSinceand no tab, the Trash is included.updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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 withtrashedAtset; once the Trash is emptied it is gone for good.kindstring | string[]Only these kinds, comma-separated:
receipt,invoice.unknownis a document with no kind set.sourcestring | string[]Only documents that arrived this way:
upload,shortcut,share_target,emailorsystem.linked"0" | "1" | "true" | "false"truefor documents attached to anything (a transaction, an inbox item or an account, whatever the key can read),falsefor those attached to nothing.fromstringFirst day (
YYYY-MM-DD) of the date a document is filed under, inclusive.tostringLast day (
YYYY-MM-DD) of the date a document is filed under, inclusive.qstringWords to find in titles, file names, notes and the text read from the pages. Every word must match.
limitintegerDocuments per page, 1 to 100. Default 50.
cursorstringpage.nextCursorfrom the previous page.
Response fields
idstringrequiredStarts with
doc_.titlestringrequiredIts title, else the file’s name, else
PhotoorPDF.titleSource"user" | "transaction" | nullrequiredWhat named it, when it was not the file.
kindstringrequiredreceipt,invoice,statement,payslip,tax,policy,warranty,letter,summary,otherorunknown.source"upload" | "shortcut" | "share_target" | "email" | "system"requiredHow it arrived.
mimeTypestringrequiredThe file type of the first file, such as
application/pdf.family"image" | "pdf"requiredWhether it is made of images or is a PDF.
partCountintegerrequiredFiles that make it up: photos of a long receipt, say.
Errors
not_found404Documents are switched off for the whole app.
unavailable503The document vault is not answering.
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
documents:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/documents?tab=unfiled&kind=receipt&limit=20' \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Search documents by meaning
/api/v1/documents/searchFinds 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.
Query parameters
qstringrequiredWhat the document is about, in your own words. At least 3 characters.
tab"all" | "unfiled" | "review" | "trash"Which documents to search, as for
GET /documents.limitintegerDocuments to return, 1 to 20. Default 10.
Response fields
idstringrequiredStarts with
doc_.titlestringrequiredIts title, else the file’s name, else
PhotoorPDF.titleSource"user" | "transaction" | nullrequiredWhat named it, when it was not the file.
kindstringrequiredreceipt,invoice,statement,payslip,tax,policy,warranty,letter,summary,otherorunknown.source"upload" | "shortcut" | "share_target" | "email" | "system"requiredHow it arrived.
mimeTypestringrequiredThe file type of the first file, such as
application/pdf.family"image" | "pdf"requiredWhether it is made of images or is a PDF.
partCountintegerrequiredFiles that make it up: photos of a long receipt, say.
Errors
unavailable503Search by meaning is switched off, or DocIntel is down or waking; retry after
Retry-After, or useGET /documents?q=.not_found404Documents are switched off for the whole app.
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
documents:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/documents/search?q=pharmacy+receipt+for+vitamins' \
-H 'Authorization: Bearer sk_your_key'{
"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
}
}Get a document
/api/v1/documents/{id}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.
Path parameters
idstringrequiredThe document, starts with
doc_.
Response fields
idstringrequiredStarts with
doc_.titlestringrequiredIts title, else the file’s name, else
PhotoorPDF.titleSource"user" | "transaction" | nullrequiredWhat named it, when it was not the file.
kindstringrequiredreceipt,invoice,statement,payslip,tax,policy,warranty,letter,summary,otherorunknown.source"upload" | "shortcut" | "share_target" | "email" | "system"requiredHow it arrived.
mimeTypestringrequiredThe file type of the first file, such as
application/pdf.family"image" | "pdf"requiredWhether it is made of images or is a PDF.
partCountintegerrequiredFiles that make it up: photos of a long receipt, say.
Errors
not_found404Documents 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.
unavailable503The document vault is not answering.
forbidden_scope403The key lacks the
documents:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/documents/doc_3b8e5d2a-7c41-4f6a-9e0d-2a1b4c6d8e0f \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}
]
}
}Read a document’s text
/api/v1/documents/{id}/textThe 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.
Path parameters
idstringrequiredThe document, starts with
doc_.
Response fields
idstringrequiredThe document id.
sourcestring | nullrequiredWhere most of the text came from: the PDF’s own text, the app’s reading of the photo, or Live Text.
charactersintegerrequiredLength of all the text, even when
pagesstops short.pagesWithTextintegerrequiredHow many pages have any text.
truncatedbooleanrequiredTrue when long documents were cut to the first 50,000 characters.
textstringrequiredThe pages joined with a blank line between them.
pagesobject[]requiredThe text page by page; stops short of
characterswhen the text was cut.pages[].pageintegerrequiredThe page number, from 1.
pages[].sourcestringrequiredWhere the text of this page came from.
pages[].textstringrequiredThe text of the page.
Errors
not_found404Documents 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.
unavailable503The document vault is not answering.
forbidden_scope403The key lacks the
documents:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/text \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
]
}
}Download a document file
/api/v1/documents/{id}/fileAnswers 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.
Path parameters
idstringrequiredThe document, starts with
doc_.
Query parameters
partintegerWhich file of a document with several photos, from 1. For
variant=pageit is the page.variant"original" | "model" | "page" | "thumb" | "unlocked" | "display"original(default),model(the copy used for reading),page(a PDF page as an image),thumborunlocked(a password-protected PDF, unlocked).download"0" | "1" | "true" | "false"trueto have the file saved rather than shown in a browser.as"link"linkanswers with{ url, expiresAt }instead of redirecting.
Response fields
urlstringrequiredA short-lived address to download the file from.
expiresAtstringrequiredWhen the address stops working, ISO 8601 in UTC.
Errors
not_found404Documents are switched off for the whole app, the document or the
partyou asked for does not exist, or storage no longer holds the file. Nothing exists with that id, or it belongs to someone else.unavailable503Document storage is down or not set up; retry after the
Retry-Afterseconds.validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
documents:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/file?as=link' \
-H 'Authorization: Bearer sk_your_key'{
"data": {
"url": "https://files.example.com/…signed…",
"expiresAt": "2026-10-26T09:01:00.000Z"
}
}Upload a document in one request
/api/v1/documentsAdds 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.
Response fields
status"added" | "duplicate"requiredaddedfor a new document,duplicatewhen the file was already there.documentIdstringThe new document. Not given for a duplicate.
urlstringWhere the document opens in the app. Not given for a duplicate.
Errors
validation_failed400The request is not a
multipart/form-dataform (reason: not_multipart) or has nofile(reason: no_file).payload_too_large413The files together are over 4 MB (
reason: too_large); usePOST /documents/uploads.rate_limited429The key has used its 200 upload calls for the UK day (
reason: daily_limit). The key has used up its rate limit; waitRetry-Afterseconds.unavailable503Document storage is down or not set up; retry after the
Retry-Afterseconds.not_found404Documents are switched off for the whole app.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
documents:uploadscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
curl -X POST https://finance.jagwebsites.xyz/api/v1/documents \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11'{
"data": {
"status": "added",
"documentId": "doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91",
"url": "https://finance.example.com/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/details"
}
}Start an upload of any size
/api/v1/documents/uploadsStep 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.
Request body (JSON)
namestring | nullThe file’s name, such as
IMG_2041.jpg.typestringrequiredThe MIME type:
image/jpeg,image/png,image/heicorapplication/pdf.sizeintegerrequiredThe file’s size in bytes.
sha256stringrequiredThe SHA-256 of the file’s bytes, in hex (64 characters).
clientOcrTextstring | nullText read on the phone (Live Text). It only helps find the transaction.
Response fields
status"upload" | "duplicate"requireduploadwhen the file should be sent toupload;duplicatewhen it is already a document.documentIdstringThe document being uploaded.
partintegerAlways 1 here.
uploadobjectSend the file to this form (a
POSToffieldsplus the file infile, or aPUTwithheaders) before it expires.upload.method"POST" | "PUT"requiredThe HTTP method to send the file with.
upload.urlstringrequiredThe address to send the file to.
upload.fieldsobjectPOSTonly: form fields to send before the file.upload.headersobjectPUTonly: headers to send with the file.upload.expiresAtstringrequiredWhen the form stops working, ISO 8601 in UTC.
Errors
rate_limited429The key has used its 200 upload calls for the UK day (
reason: daily_limit). The key has used up its rate limit; waitRetry-Afterseconds.unavailable503Document storage is down or not set up; retry after the
Retry-Afterseconds.not_found404Documents are switched off for the whole app.
validation_failed400A body field is missing, wrong, or not one this endpoint knows;
detailslists each.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
documents:uploadscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
curl -X POST https://finance.jagwebsites.xyz/api/v1/documents/uploads \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"name": "IMG_2041.jpg",
"type": "image/jpeg",
"size": 184320,
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}'{
"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"
}
}
}Add a page to an upload
/api/v1/documents/{id}/partsAnother 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.
Path parameters
idstringrequiredThe document, starts with
doc_.
Request body (JSON)
namestring | nullThe file’s name, such as
IMG_2041.jpg.typestringrequiredThe MIME type:
image/jpeg,image/png,image/heicorapplication/pdf.sizeintegerrequiredThe file’s size in bytes.
sha256stringrequiredThe SHA-256 of the file’s bytes, in hex (64 characters).
clientOcrTextstring | nullText read on the phone (Live Text). It only helps find the transaction.
partintegerrequiredThe page this file is: 2 for the second, and so on. A retry sends the same number.
Response fields
documentIdstringrequiredThe document this page belongs to.
partintegerrequiredThe page number this upload is for.
uploadobjectrequiredWhere to send the file’s bytes.
upload.method"POST" | "PUT"requiredThe HTTP method to send the file with.
upload.urlstringrequiredThe address to send the file to.
upload.fieldsobjectPOSTonly: form fields to send before the file.upload.headersobjectPUTonly: headers to send with the file.upload.expiresAtstringrequiredWhen the form stops working, ISO 8601 in UTC.
Errors
not_found404The upload does not exist, is not yours, or has already been finished. Nothing exists with that id, or it belongs to someone else.
rate_limited429The key has used its 200 upload calls for the UK day (
reason: daily_limit). The key has used up its rate limit; waitRetry-Afterseconds.unavailable503Document storage is down or not set up; retry after the
Retry-Afterseconds.validation_failed400A body field is missing, wrong, or not one this endpoint knows;
detailslists each.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
documents:uploadscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
curl -X POST https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/parts \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"name": "IMG_2042.jpg",
"type": "image/jpeg",
"size": 201776,
"sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
"part": 2
}'{
"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"
}
}
}Finish an upload
/api/v1/documents/{id}/completeThe 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.
Path parameters
idstringrequiredThe document, starts with
doc_.
Response fields
status"added" | "duplicate"requiredaddedfor a new document,duplicatewhen the file was already there.documentIdstringNot given for a duplicate.
urlstringWhere the document opens in the app. Not given for a duplicate.
Errors
conflict409A page has not arrived yet (
reason: not_uploaded); send it, then try again.not_found404Documents 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.
unavailable503Document storage is down or not set up; retry after the
Retry-Afterseconds.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
documents:uploadscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/complete \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11'{
"data": {
"status": "added",
"documentId": "doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91",
"url": "https://finance.example.com/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/details"
}
}Change a document’s details
/api/v1/documents/{id}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.
Path parameters
idstringrequiredThe document, starts with
doc_.
Request body (JSON)
titlestring | nullA new title, up to 200 characters.
nullor blank means the file’s name.kind"receipt" | "invoice" | "statement" | "payslip" | "tax" | "policy" | "warranty" | "letter" | "summary" | "other" | "unknown"receipt,invoice,statement,payslip,tax,policy,warranty,letter,summary,otherorunknown(not set).notesstring | nullYour notes, up to 5000 characters.
nullor blank clears them.datestring | nullThe day it is dated,
YYYY-MM-DD, from 2000 to tomorrow.nullclears it (and its time), so it is filed under when it was taken or arrived again.timestring | nullThe time of that day it is dated,
HH:MMon the UK clock (Europe/London); it needs a date, sent with it or already set.nullclears it. Left out, it stays, unlessdatechanges to another day.paidDatestring | nullThe day it was paid,
YYYY-MM-DD, for a document on no transaction (one on a transaction is paid that transaction’s day).nullclears it.reviewedbooleantruefiles a document waiting in the Documents inbox without a transaction;falsesends it to the Documents inbox, from anywhere in the vault. What it is attached to stays.versionstringThe
versionyou last read; the same as sendingIf-Match.
Response fields
idstringrequiredStarts with
doc_.titlestringrequiredIts title, else the file’s name, else
PhotoorPDF.titleSource"user" | "transaction" | nullrequiredWhat named it, when it was not the file.
kindstringrequiredreceipt,invoice,statement,payslip,tax,policy,warranty,letter,summary,otherorunknown.source"upload" | "shortcut" | "share_target" | "email" | "system"requiredHow it arrived.
mimeTypestringrequiredThe file type of the first file, such as
application/pdf.family"image" | "pdf"requiredWhether it is made of images or is a PDF.
partCountintegerrequiredFiles that make it up: photos of a long receipt, say.
Errors
validation_failed400The body is empty, or
kindis not one of the document kinds. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404Documents 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.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
documents:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91 \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"' \
-H 'Content-Type: application/json' \
-d '{
"title": "Boots vitamins",
"kind": "receipt",
"reviewed": true
}'{
"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"
}
}
]
}
}Attach a document
/api/v1/documents/{id}/linksAttaches 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.
Path parameters
idstringrequiredThe document, starts with
doc_.
Request body (JSON)
targetType"transaction" | "account" | "inbox"requiredWhat to attach it to.
targetIdstringrequiredThe transaction, account or inbox item.
periodStartstringAccounts only: the first day of the statement period (
YYYY-MM-DD).periodEndstringAccounts only: the last day of the statement period.
Response fields
idstringrequiredThe link, starts with
dln_.targetType"transaction" | "inbox_item" | "account"requiredWhat kind of thing it is attached to.
targetIdstringrequiredThe transaction, inbox item or account it is attached to.
linkSource"user" | "auto_match" | "system" | nullrequiredWho attached it. Not given for accounts.
periodStartstring | nullrequiredAccounts only: the statement period, first day.
periodEndstring | nullrequiredAccounts only: the statement period, last day.
Errors
forbidden_scope403The key cannot also read the area of the target:
transactions:read,inbox:readoraccounts:read. The key lacks thedocuments:writescope;requiredScopenames it.validation_failed400periodStartorperiodEndis sent for something other than an account. A body field is missing, wrong, or not one this endpoint knows;detailslists each.not_found404Documents 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.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/links \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"targetType": "transaction",
"targetId": "a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b"
}'{
"data": {
"id": "dln_0a7b9c1d-3e5f-4a6b-8c7d-9e0f1a2b3c4d",
"targetType": "transaction",
"targetId": "a3a8e0b2-1c4d-4e6f-8a9b-0c1d2e3f4a5b",
"linkSource": "user",
"periodStart": null,
"periodEnd": null
}
}Detach a document
/api/v1/documents/{id}/links/{linkId}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.
Path parameters
idstringrequiredThe document, starts with
doc_.linkIdstringrequiredThe attachment, starts with
dln_.
Errors
not_found404The document or the link does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
documents:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X DELETE https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/links/dln_0a7b9c1d-3e5f-4a6b-8c7d-9e0f1a2b3c4d \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"'204 with no body.
Move a document to the Trash
/api/v1/documents/{id}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.
Path parameters
idstringrequiredThe document, starts with
doc_.
Errors
not_found404Documents 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.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
documents:deletescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X DELETE https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91 \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"'204 with no body.
Restore a document from the Trash
/api/v1/documents/{id}/restoreBrings 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.
Path parameters
idstringrequiredThe document, starts with
doc_.
Response fields
idstringrequiredStarts with
doc_.titlestringrequiredIts title, else the file’s name, else
PhotoorPDF.titleSource"user" | "transaction" | nullrequiredWhat named it, when it was not the file.
kindstringrequiredreceipt,invoice,statement,payslip,tax,policy,warranty,letter,summary,otherorunknown.source"upload" | "shortcut" | "share_target" | "email" | "system"requiredHow it arrived.
mimeTypestringrequiredThe file type of the first file, such as
application/pdf.family"image" | "pdf"requiredWhether it is made of images or is a PDF.
partCountintegerrequiredFiles that make it up: photos of a long receipt, say.
Errors
conflict409The same file was added again while this one was in the Trash (
reason: duplicate).not_found404Documents 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.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
documents:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/restore \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11'{
"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"
}
}
]
}
}Inbox
6 endpoints
List inbox items
/api/v1/inboxWallet 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.
Query parameters
updatedSincestringOnly 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 thepage.asOfof your last run (of its first page, if it took several), not the newestupdatedAtyou 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 bystatus), oldest first, and without suggestions for those no longer pending.limitintegerItems per page, 1 to 50. Default 50.
cursorstringpage.nextCursorfrom the previous page.
Response fields
idstringrequiredThe inbox item id.
status"pending" | "approved" | "dismissed" | "expired"requiredpendingwaits for you;approvedbecame a transaction;dismissedwas thrown away;expiredwas left too long.merchantstringrequiredThe merchant as the wallet sent it.
amountMinorintegerrequiredWhole pence, negative for money spent. 0 when the purchase arrived without an amount.
amountDisplaystringrequiredThe amount ready to show, such as -£4.80.
hasAmountbooleanrequiredFalse when the purchase arrived without an amount and waits for you to fill it in.
originalobject | nullrequiredWhat was charged in the merchant’s own currency, for a foreign purchase.
original.currencystringrequiredThe three-letter currency code charged, such as EUR.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
inbox:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/inbox?limit=20' \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Get an inbox item
/api/v1/inbox/{id}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.
Path parameters
idstringrequiredThe inbox item.
Response fields
idstringrequiredThe inbox item id.
status"pending" | "approved" | "dismissed" | "expired"requiredpendingwaits for you;approvedbecame a transaction;dismissedwas thrown away;expiredwas left too long.merchantstringrequiredThe merchant as the wallet sent it.
amountMinorintegerrequiredWhole pence, negative for money spent. 0 when the purchase arrived without an amount.
amountDisplaystringrequiredThe amount ready to show, such as -£4.80.
hasAmountbooleanrequiredFalse when the purchase arrived without an amount and waits for you to fill it in.
originalobject | nullrequiredWhat was charged in the merchant’s own currency, for a foreign purchase.
original.currencystringrequiredThe three-letter currency code charged, such as EUR.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
inbox:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/inbox/wallet_import_id \
-H 'Authorization: Bearer sk_your_key'{
"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
}
}Add a purchase to the inbox
/api/v1/inboxQueues 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.
Request body (JSON)
merchantstring | nullThe merchant or title shown in the inbox. Leave it out when the wallet cannot say.
amountMinorinteger | nullPence spent, as a positive whole number (
495is £4.95). Leave it out, or send 0, for a purchase that arrived without an amount: it waits for you to fill it in.transactionDatestringThe day of the purchase:
YYYY-MM-DDor an ISO 8601 date-time (no offset means UK time). Wins overdate. Dates like05/10/2026are refused: the day and month order would be a guess.datestringThe same as
transactionDate, for clients that call it this.cardstringThe card label the wallet sent, such as
Visa •• 4242. It helps pick the account.namestringThe name of the Shortcut sending this.
idempotencyKeystringMakes a retry safe, like the
Idempotency-Keyheader (send either; if both, they must match). A purchase already queued under this key is answered again, not queued twice.metadataobjectAnything else worth keeping with the purchase. Kept as sent and shown in its history.
originalCurrencystring | nulloriginalAmountMinorinteger | nullfxRatenumber | string | nullfxSource"manual" | "derived" | "frankfurter" | nullfxAsOfstring | null
Response fields
idstringrequiredThe inbox item id.
status"pending" | "approved" | "dismissed" | "expired"requiredpendingwaits for you;approvedbecame a transaction;dismissedwas thrown away;expiredwas left too long.merchantstringrequiredThe merchant as the wallet sent it.
amountMinorintegerrequiredWhole pence, negative for money spent. 0 when the purchase arrived without an amount.
amountDisplaystringrequiredThe amount ready to show, such as -£4.80.
hasAmountbooleanrequiredFalse when the purchase arrived without an amount and waits for you to fill it in.
originalobject | nullrequiredWhat was charged in the merchant’s own currency, for a foreign purchase.
original.currencystringrequiredThe three-letter currency code charged, such as EUR.
Errors
validation_failed400The
Idempotency-Keyheader and theidempotencyKeyin the body differ, or the foreign-currency amounts do not add up. A body field is missing, wrong, or not one this endpoint knows;detailslists each.invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
wallet:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/inbox \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"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"
}'{
"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
}
}Approve an inbox item
/api/v1/inbox/{id}/approvePosts 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.
Path parameters
idstringrequiredThe inbox item.
Request body (JSON)
categoryIdstringThe category to post under. Left out, the one saved for this merchant is used.
payeeIdstringThe payee. Left out, the one saved for this merchant is used.
accountIdstringThe 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.
descriptionstringThe transaction’s description. Left out, the merchant as the wallet sent it.
amountMinorintegerPence to post, as a positive whole number. Needed when the purchase arrived without an amount; also corrects one.
Response fields
idstringrequiredThe inbox item id.
status"pending" | "approved" | "dismissed" | "expired"requiredpendingwaits for you;approvedbecame a transaction;dismissedwas thrown away;expiredwas left too long.merchantstringrequiredThe merchant as the wallet sent it.
amountMinorintegerrequiredWhole pence, negative for money spent. 0 when the purchase arrived without an amount.
amountDisplaystringrequiredThe amount ready to show, such as -£4.80.
hasAmountbooleanrequiredFalse when the purchase arrived without an amount and waits for you to fill it in.
originalobject | nullrequiredWhat was charged in the merchant’s own currency, for a foreign purchase.
original.currencystringrequiredThe three-letter currency code charged, such as EUR.
Errors
validation_failed400The account, category or payee cannot be worked out (
reason: missing_fields;detailsnames what to send), or the purchase has no amount. A body field is missing, wrong, or not one this endpoint knows;detailslists each.conflict409The item is not pending: it was already approved, dismissed or has expired (
reason: not_pending).not_found404The 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.
invalid_json400The body is not valid JSON.
unsupported_media_type415The body is not JSON; send
Content-Type: application/json.payload_too_large413The body is over the 1 MB limit.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
inbox:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/inbox/wallet_import_id/approve \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'Content-Type: application/json' \
-d '{
"categoryId": "category_id",
"description": "Lunch with Sam"
}'{
"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"
}
}Dismiss an inbox item
/api/v1/inbox/{id}/dismissSets 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.
Path parameters
idstringrequiredThe inbox item.
Response fields
idstringrequiredThe inbox item id.
status"pending" | "approved" | "dismissed" | "expired"requiredpendingwaits for you;approvedbecame a transaction;dismissedwas thrown away;expiredwas left too long.merchantstringrequiredThe merchant as the wallet sent it.
amountMinorintegerrequiredWhole pence, negative for money spent. 0 when the purchase arrived without an amount.
amountDisplaystringrequiredThe amount ready to show, such as -£4.80.
hasAmountbooleanrequiredFalse when the purchase arrived without an amount and waits for you to fill it in.
originalobject | nullrequiredWhat was charged in the merchant’s own currency, for a foreign purchase.
original.currencystringrequiredThe three-letter currency code charged, such as EUR.
Errors
not_found404The 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.
idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
inbox:writescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X POST https://finance.jagwebsites.xyz/api/v1/inbox/wallet_import_id/dismiss \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11'{
"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"
}
}
}Delete a dismissed inbox item
/api/v1/inbox/{id}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.
Path parameters
idstringrequiredThe inbox item.
Errors
not_found404The 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.
version_conflict412The
If-Matchversion (orversionin the body) is out of date; read the item again and retry.idempotency_in_progress409A call with the same
Idempotency-Keyis still running; wait, then retry.idempotency_outcome_unknown409The first call with this
Idempotency-Keymay have completed but its answer was lost; check the data before retrying.idempotency_conflict422The
Idempotency-Keywas already used with a different request.forbidden_scope403The key lacks the
inbox:deletescope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl -X DELETE https://finance.jagwebsites.xyz/api/v1/inbox/wallet_import_id \
-H 'Authorization: Bearer sk_your_key' \
-H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
-H 'If-Match: "1761480000000"'204 with no body.
Insights
8 endpoints
Income, spending and net for a range
/api/v1/insights/totalsIncome, 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.
Query parameters
fromstringStart of the range:
YYYY-MM-DD(that whole UK day) or an ISO 8601 timestamp. Default: 29 days beforeto.tostringEnd of the range, included:
YYYY-MM-DD(that whole UK day) or an ISO 8601 timestamp. Default: today.groupBy"day" | "week" | "month" | "none"How to split the range:
day,week,monthornone(one group, the default).
Response fields
startstringrequiredFirst UK day of the group inside the range.
endstringrequiredLast UK day of the group inside the range.
lineCountintegerrequiredLedger lines counted.
incomeMinorintegerrequiredIncome, in whole pence.
incomeDisplaystringrequiredIncome, ready to show, such as £12.50.
spendingMinorintegerrequiredSpending, in whole pence.
spendingDisplaystringrequiredSpending, ready to show, such as £12.50.
netMinorintegerrequiredNet, in whole pence.
netDisplaystringrequiredNet, ready to show, such as £12.50.
Errors
validation_failed400fromis afterto, the range is longer than 3,660 days, orgroupBy=daycovers more than 366 days. A query parameter is wrong, or not one this endpoint knows;detailslists each.forbidden_scope403The key lacks the
totals:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/insights/totals?from=2026-10-01&to=2026-10-31&groupBy=month' \
-H 'Authorization: Bearer sk_your_key'{
"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
}
}Cash flow over time
/api/v1/insights/cash-flowThe 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.
Query parameters
fromstringStart of the range:
YYYY-MM-DD(that whole UK day) or an ISO 8601 timestamp. Default: 29 days beforeto.tostringEnd of the range, included:
YYYY-MM-DD(that whole UK day) or an ISO 8601 timestamp. Default: today.interval"day" | "week" | "month"One row per
day(the default),week(Monday to Sunday) ormonth.
Response fields
startstringrequiredFirst UK day of the point inside the range.
endstringrequiredLast UK day of the point inside the range.
lineCountintegerrequiredLedger lines counted.
incomeMinorintegerrequiredIncome, in whole pence.
incomeDisplaystringrequiredIncome, ready to show, such as £12.50.
spendingMinorintegerrequiredSpending, in whole pence.
spendingDisplaystringrequiredSpending, ready to show, such as £12.50.
netMinorintegerrequiredNet, in whole pence.
netDisplaystringrequiredNet, ready to show, such as £12.50.
balanceMinorintegerrequiredBalance of all accounts at the end of the point, in whole pence.
balanceDisplaystringrequiredBalance of all accounts at the end of the point, ready to show, such as £12.50.
Errors
validation_failed400fromis afterto, 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;detailslists each.forbidden_scope403The key lacks the
insights:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/insights/cash-flow?from=2026-10-01&to=2026-10-31&interval=week' \
-H 'Authorization: Bearer sk_your_key'{
"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
}
}Where the money went
/api/v1/insights/spendingThe 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.
Query parameters
fromstringStart of the range:
YYYY-MM-DD(that whole UK day) or an ISO 8601 timestamp. Default: 29 days beforeto.tostringEnd of the range, included:
YYYY-MM-DD(that whole UK day) or an ISO 8601 timestamp. Default: today.by"category" | "payee"Group by
category(the default) orpayee.limitintegerHow many rows, 1 to 100. Default 10.
Response fields
idstring | nullrequiredThe category or payee id; null for spending with no category or payee.
namestringrequiredThe category or payee name.
pathstring | nullrequiredThe category with its parents, such as
Home › Bills.sharePercentnumberrequiredShare of
meta.totalSpending(all spending in the range), 0 to 100, one decimal.lineCountintegerrequiredLedger lines counted.
spendingMinorintegerrequiredSpending, in whole pence.
spendingDisplaystringrequiredSpending, ready to show, such as £12.50.
Errors
validation_failed400fromis afterto, or the range is longer than 3,660 days. A query parameter is wrong, or not one this endpoint knows;detailslists each.forbidden_scope403The key lacks the
insights:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/insights/spending?from=2026-10-01&to=2026-10-31&by=category&limit=5' \
-H 'Authorization: Bearer sk_your_key'{
"data": [
{
"id": "cat_1",
"name": "Groceries",
"path": "Food › Groceries",
"spendingMinor": 41230,
"spendingDisplay": "£412.30",
"sharePercent": 22,
"lineCount": 18
}
],
"page": {
"nextCursor": null,
"hasMore": false
}
}Net worth and how it changed
/api/v1/insights/net-worthThe 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.
Query parameters
fromstringStart of the range:
YYYY-MM-DD(that whole UK day) or an ISO 8601 timestamp. Default: 29 days beforeto.tostringEnd of the range, included:
YYYY-MM-DD(that whole UK day) or an ISO 8601 timestamp. Default: today.
Response fields
fromstringrequiredThe day the change is measured from.
asOfstringrequiredThe balance is as at the end of this day.
netWorthMinorintegerrequiredNet worth, in whole pence.
netWorthDisplaystringrequiredNet worth, ready to show, such as £12.50.
openingNetWorthMinorintegerrequiredOpening net worth, in whole pence.
openingNetWorthDisplaystringrequiredOpening net worth, ready to show, such as £12.50.
changeMinorintegerrequiredChange, in whole pence.
changeDisplaystringrequiredChange, ready to show, such as £12.50.
Errors
validation_failed400fromis afterto, or the range is longer than 3,660 days. A query parameter is wrong, or not one this endpoint knows;detailslists each.forbidden_scope403The key lacks the
insights:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/insights/net-worth \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Cash forecast and safe to spend
/api/v1/insights/forecastThe 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.
Query parameters
daysnumberHow far ahead: 7, 14, 30, 60, 90 or 180 days. Default 30.
Response fields
todaystringrequiredToday, in UK time.
throughOnstringrequiredThe last day the forecast covers.
budgetsEnabledbooleanrequiredWhether budgets are switched on, so unscheduled budget spending is included.
safeToSpendobjectrequiredWhat can be spent without leaving a bill uncovered, and how it is made up.
safeToSpend.throughOnstringrequiredThe last day counted.
safeToSpend.postedCashAccountsobject[]requiredThe cash accounts whose posted balances are counted.
safeToSpend.keptAsideAccountsobject[]requiredAccounts kept aside, left out of the figures.
safeToSpend.startingCashMinorintegerrequiredStarting cash, in whole pence.
Errors
validation_failed400daysis not 7, 14, 30, 60, 90 or 180. A query parameter is wrong, or not one this endpoint knows;detailslists each.forbidden_scope403The key lacks the
insights:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/insights/forecast?days=30' \
-H 'Authorization: Bearer sk_your_key'{
"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": []
}
}Cash runway
/api/v1/insights/runwayThe 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.
Response fields
todaystringrequiredA UK calendar day, YYYY-MM-DD.
runwayDaysinteger | nullrequiredWhole days of cover before cash first runs out; null if it never does in the next 90 days.
firstNegativeOnstring | nullrequiredThe first day cash is projected to go below zero; null if it does not.
liquidityRunwayDaysinteger | nullrequiredThe same, counting unused credit.
creditUtilisationPercentnumber | nullrequiredHow much of the credit limit is used, as a percentage; null with no credit.
workingDayShiftedCountintegerrequiredHow many payments were moved to the next working day.
overdueobjectrequiredCash already past the day it was due to move. Items that do not change planning cash are left out.
overdue.itemCountintegerrequiredHow many bills and payments it covers.
Errors
forbidden_scope403The key lacks the
insights:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/insights/runway \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
]
}
}Period summaries
/api/v1/summariesThe 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}.
Query parameters
type"weekly" | "monthly" | "quarterly" | "annual" | "biweekly" | "fourweekly"The kind of period: weekly, biweekly, fourweekly, monthly, quarterly or annual. Default monthly.
limitintegerRows per page, 1 to 200.
cursorstringThe
nextCursorof the previous page.
Response fields
idstringrequiredThe id of the latest saved version of this period.
type"weekly" | "biweekly" | "fourweekly" | "monthly" | "quarterly" | "annual"requiredThe length of the period.
periodKeystringrequiredFor example
2026-10or2026-W41.periodStartstringrequiredThe first day of the period.
periodEndstringrequiredThe last day of the period.
partialbooleanrequiredThe version was written while the period was still open.
versionintegerrequiredWhich saved version of the period this is; 1 is the first.
versionCountintegerrequiredHow many versions of the period are saved.
Errors
validation_failed400A query parameter is wrong, or not one this endpoint knows;
detailslists each.forbidden_scope403The key lacks the
insights:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/summaries?type=monthly' \
-H 'Authorization: Bearer sk_your_key'{
"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
}
}One period summary
/api/v1/summaries/{id}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).
Path parameters
idstringrequiredA summary version id from
/summaries.
Response fields
idstringrequiredThe id of the latest saved version of this period.
type"weekly" | "biweekly" | "fourweekly" | "monthly" | "quarterly" | "annual"requiredThe length of the period.
periodKeystringrequiredFor example
2026-10or2026-W41.periodStartstringrequiredThe first day of the period.
periodEndstringrequiredThe last day of the period.
partialbooleanrequiredThe version was written while the period was still open.
versionintegerrequiredWhich saved version of the period this is; 1 is the first.
versionCountintegerrequiredHow many versions of the period are saved.
Errors
not_found404Nothing exists with that id, or it belongs to someone else.
forbidden_scope403The key lacks the
insights:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl https://finance.jagwebsites.xyz/api/v1/summaries/sum_1 \
-H 'Authorization: Bearer sk_your_key'{
"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"
}
}Search
1 endpoint
Search everything
/api/v1/searchOne 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.
Query parameters
qstringrequiredWhat to look for. Every word must match. At least 2 characters.
typesstring | string[]Only these kinds of result, comma-separated:
transaction,account,payee,category,tag,bill,document(plurals work too). Default: every kind the key can read.limitintegerResults of each kind, 1 to 20. Default 5.
Response fields
type"transaction" | "account" | "payee" | "category" | "tag" | "bill" | "document"requiredWhat sort of thing it is, such as
transactionordocument.idstringrequiredThe id to use with that type’s own endpoint, such as
GET /transactions/{id}.titlestringrequiredIts name or description.
subtitlestring | nullrequiredA second line of context: the payee and account, the institution, the document kind.
datestring | nullrequiredYYYY-MM-DD: a transaction’s or document’s day, a bill’s next due date.amountMinorinteger | nullrequiredWhole pence, negative for money out. 0 for a transfer between your own accounts.
nullfor things without an amount.amountDisplaystring | nullrequiredThe amount ready to show, or null.
Errors
validation_failed400qis missing or too short, ortypesnames something that cannot be searched. A query parameter is wrong, or not one this endpoint knows;detailslists each.forbidden_scope403The key lacks the
search:readscope;requiredScopenames it.forbidden403The key is limited to some accounts, and this area spans all of them (
reason: account_limit).unauthorized401No API key was sent, or the key is not valid.
key_expired401The key has passed its expiry date.
key_revoked401The key was revoked.
rate_limited429The key has used up its rate limit; wait
Retry-Afterseconds.
curl 'https://finance.jagwebsites.xyz/api/v1/search?q=tesco&types=transaction%2Cpayee' \
-H 'Authorization: Bearer sk_your_key'{
"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
}
}