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

Endpoints

All endpoints
Meta6
Accounts6
Transactions9
Categories5
Payees4
Tags5
Bills15
Budgets5
Goals5
Documents15
Inbox6
Insights8
Search1

Getting started

  1. Create a key in Settings → API keys, giving it only the access it needs. Its secret starts sk_ and is shown once.
  2. Send it with every call, as below.
  3. Every endpoint lives under the base address. Tools can read the whole API from the OpenAPI file; it needs no key.
Base URL
https://finance.jagwebsites.xyz/api/v1
Your first call
curl 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

  1. Add Get Contents of URL, tap URL and type the address of the endpoint, such as https://finance.jagwebsites.xyz/api/v1/me.
  2. Tap Show More and choose the Method: GET to read, POST to add something.
  3. Under Headers add one: the key Authorization and the text Bearer sk_your_key, with your own key after the word Bearer and a space.
  4. 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).

  1. Current Date.
  2. Format Date: Date Format Custom, format yyyy-MM-dd. This gives today as 2026-10-26.
  3. Text: https://finance.jagwebsites.xyz/api/v1/insights/totals?from=, then the Formatted Date variable, then &to=, then the Formatted Date again.
  4. Get Contents of URL with that Text as the URL, Method GET and the Authorization header.
  5. Get Dictionary Value: Value for data. It is a list with one entry, the whole day.
  6. Get Item from List: First Item.
  7. Get Dictionary Value: Value for spendingDisplay.
  8. 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.

  1. Ask for Input: type Number, prompt How much?.
  2. Calculate: Provided Input × 100, then Round Number to Ones Place. That is the amount in pence.
  3. Ask for Input: type Text, prompt What was it?.
  4. Current Date, then Format Date as yyyy-MM-dd.
  5. Get Contents of URL: URL https://finance.jagwebsites.xyz/api/v1/transactions, Method POST, the Authorization header, Request Body JSON with the fields shown beside this: date, description, kind (expense), accountId, categoryId, payeeId and amountMinor as a Number.
  6. Get Dictionary Value: Value for data, then again for amountDisplay.
  7. 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.

Recipe 1: the request
GET https://finance.jagwebsites.xyz/api/v1/insights/totals?from=2026-10-26&to=2026-10-26
Authorization: Bearer sk_your_key
Recipe 1: the answer
{
  "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
    }
  ]
}
Recipe 2: the Request Body (JSON)
{
  "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.

Headers
Authorization: Bearer sk_your_key
# or
x-api-key: sk_your_key

Errors

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 400
{
  "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.

A page
{
  "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:

  1. The first time, fetch everything (follow nextCursor) and store the page.asOf of the first page.
  2. Next time, send that value as updatedSince, update your copy by id, and store the new page.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.

Since the last run
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.

An amount
{
  "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.

October so far
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.

A safe retry
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.

Edit only if unchanged
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.

Response headers
RateLimit-Limit: 1000
RateLimit-Remaining: 997
RateLimit-Reset: 1260

Scopes

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:read

    Read accounts. Institutions, accounts, cards and pots, balances and balance checks.

    • GET/accounts
    • GET/accounts/{id}
    • GET/institutions
    • GET/accounts/{id}/balance-checks
  • accounts:write

    Change accounts. Rename, close or set keep-aside on accounts; record balance checks.

    • POST/accounts/{id}/balance-checks
    • PATCH/accounts/{id}
  • transactions:read

    Read transactions. Transactions, their lines and tags.

    • GET/transactions
    • GET/transactions/lines
    • GET/transactions/{id}
    • GET/transactions/export
  • transactions:write

    Change transactions. Create and edit transactions, their notes and tags.

    • POST/transactions
    • PATCH/transactions/{id}
    • PUT/transactions/{id}/tags
    • POST/transactions/batch
  • transactions:delete

    Delete transactions. Delete transactions.

    • DELETE/transactions/{id}
  • bills:read

    Read bills. Upcoming bills, recurring payments and scheduled items.

    • GET/bills/upcoming
    • GET/recurring
    • GET/recurring/{id}
    • GET/scheduled
    • GET/scheduled/{id}
  • bills:write

    Change 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
  • bills:delete

    Delete bills. Cancel scheduled items.

    • POST/scheduled/{id}/cancel
  • budgets:read

    Read budgets. Budgets and how much is left.

    • GET/budgets
    • GET/budgets/{id}
  • budgets:write

    Change budgets. Create budgets and set their amounts.

    • POST/budgets
    • PATCH/budgets/{id}
    • PUT/budgets/{id}/months/{month}
  • goals:read

    Read goals. Goals and their funding.

    • GET/goals
    • GET/goals/{id}
  • goals:write

    Change goals. Create and edit goals; add funding.

    • POST/goals
    • PATCH/goals/{id}
    • POST/goals/{id}/funding
  • categories:read

    Read categories. Categories and categorisation rules.

    • GET/categories
    • GET/categories/{id}
    • GET/rules
  • categories:write

    Change categories. Create, edit and archive categories.

    • POST/categories
    • PATCH/categories/{id}
  • payees:read

    Read payees. Payees.

    • GET/payees
    • GET/payees/{id}
  • payees:write

    Change payees. Create, edit, archive and restore payees.

    • POST/payees
    • PATCH/payees/{id}
  • tags:read

    Read tags. Tags.

    • GET/tags
    • GET/tags/{id}
  • tags:write

    Change tags. Create and rename tags.

    • POST/tags
    • PATCH/tags/{id}
  • tags:delete

    Delete tags. Delete tags.

    • DELETE/tags/{id}
  • documents:read

    Read documents. Documents, their text and files.

    • GET/documents
    • GET/documents/search
    • GET/documents/{id}
    • GET/documents/{id}/text
    • GET/documents/{id}/file
  • documents:write

    Change 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
  • documents:delete

    Delete documents. Move documents to the trash.

    • DELETE/documents/{id}
  • inbox:read

    Read inbox. Wallet purchases waiting for review.

    • GET/inbox
    • GET/inbox/{id}
  • inbox:write

    Change inbox. Add, approve and dismiss them.

    • POST/inbox/{id}/approve
    • POST/inbox/{id}/dismiss
  • inbox:delete

    Delete inbox. Delete dismissed items.

    • DELETE/inbox/{id}
  • insights:read

    Read 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}
  • search:read

    Read search. Search across the areas this key can read.

    • GET/search
  • totals:readShortcut-only

    Read 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
  • wallet:writeShortcut-only

    Add 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
  • documents:uploadShortcut-only

    Add 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

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).

Download
curl -o jag-finance.ts https://finance.jagwebsites.xyz/api/v1/client.ts
A first call
import { 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() });
Every page
// Follows nextCursor until the last page.
for await (const transaction of api.getTransactionsAll({ query: { from: '2026-01-01' } })) {
  console.log(transaction.date, transaction.amountDisplay);
}
Errors
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.

Request headers
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…
Body: transaction.created
{
  "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"
    }
  }
}
Verify in Node.js
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)
Verify in Python
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

6 endpoints

The key making the request

GET/api/v1/me
Needs Any key

Who the key belongs to and what it may do. Any valid key can call it, so it is the quickest way to check a key works. accountLimit lists the accounts a key limited to some accounts may use (null for every account).

Response fields

  • keyobjectrequired

    The key making the request.

  • key.idstringrequired

    The key id (not the secret).

  • key.namestring | nullrequired

    The name you gave the key.

  • key.scopesstring[]required

    What the key may do, such as accounts:read.

  • key.createdAtstring | nullrequired

    When the key was created, ISO 8601 in UTC.

  • key.expiresAtstring | nullrequired

    When the key stops working, ISO 8601 in UTC; null if it never does.

  • key.lastUsedAtstring | nullrequired

    When the key was last used, ISO 8601 in UTC; null if never.

  • userobjectrequired

    Who the key belongs to.

Errors

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/me \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/connection
Needs Any key

For a connected app (OAuth token): what the person allowed it, the accounts it can see and its webhook. A key gets 403.

Response fields

  • grantIdstringrequired

    The connection.

  • appobjectrequired

    The app it is for.

  • app.clientIdstringrequired

    Its client id, such as jag-work.

  • app.namestringrequired

    Its name.

  • scopesstring[]required

    What the app may do.

  • accountsobject[]required

    The accounts the person allowed it to see.

  • accounts[].idstringrequired

    The account id.

  • accounts[].namestringrequired

    Its name.

Errors

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/connection \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

PUT/api/v1/connection/webhook
Needs Any key

Makes the connection’s webhook, or moves it to a new address. Every call answers with a new signing secret (whsec_…), shown only here. It is told about transaction.created, transaction.updated, transaction.deleted, document.attached, document.detached, on the allowed accounts only, with ids and no figures, and connection.revoked once when access ends.

Request body (JSON)

  • urlstringrequired

    Where to send events: an https address.

Response fields

  • idstringrequired

    The webhook.

  • urlstring | nullrequired

    Where events go.

  • eventsstring[]required

    What it is told about.

  • secretstringrequired

    Signs each request (JAG-Signature). Store it; it is not shown again.

Errors

  • validation_failed400

    A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 200
{
  "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

DELETE/api/v1/connection/webhook
Needs Any key

Stops sending events to the connection’s webhook.

Errors

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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

GET/api/v1/openapi.json
Needs No key needed

Every endpoint with its scope, inputs and outputs, generated from the code that serves them. Needs no key and holds no data, so tools can fetch it freely.

Response fields

  • openapistringrequired

    The OpenAPI version, 3.1.0.

  • infoobjectrequired

    About the API.

  • info.titlestringrequired

    The name of the API.

  • info.versionstringrequired

    The version of the API.

  • serversobject[]required

    Where the API is served.

  • servers[].urlstringrequired

    The base address of the API.

  • pathsobjectrequired

    Every endpoint, by path then method.

  • componentsobjectrequired

    Shared schemas, parameters and responses the endpoints refer to.

Request
curl https://finance.jagwebsites.xyz/api/v1/openapi.json
Response 200
{
  "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

GET/api/v1/client.ts
Needs No key needed

One self-contained TypeScript file with a type for every request and answer and a method for every endpoint (createJagFinanceClient({ apiKey })), generated from the same code as the OpenAPI file. Save it into your project (curl -o jag-finance.ts …/client.ts) and import it: no package to install. Needs no key and holds no data.

Request
curl https://finance.jagwebsites.xyz/api/v1/client.ts
Response 200
export function createJagFinanceClient(options: JagFinanceClientOptions) {
  // …one method per endpoint, such as getTransactions({ query })
}

Accounts

6 endpoints

List accounts

GET/api/v1/accounts
Needs accounts:read

Every financial account with its current balance (the figure the Accounts page shows: lines dated in the future count once their day comes). Closed accounts are hidden unless closed=include or closed=only. Each account lists its targets, the payment sources (the account itself, cards, pots) that transactions are posted against. A credit account's balance is negative when money is owed. To keep a copy in step, send updatedSince: only accounts edited since then come back, closed ones included and flagged. An account counts as edited when the account or one of its targets changes (renamed, closed, limit, a card added); balance moves with your transactions without that, so refresh the balances you show. A connected app gets its accounts without balance or creditLimit.

Query parameters

  • closed"exclude" | "include" | "only"

    Closed accounts: exclude (default), include or only. With updatedSince the default is include, so a closing shows.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

Response fields

  • idstringrequired

    The account id.

  • namestringrequired

    The account name.

  • institutionobjectrequired

    The bank or provider it is held with.

  • institution.idstringrequired

    Its id.

  • institution.namestringrequired

    Its name.

  • kind"current" | "savings" | "credit" | "cash"required

    What sort of account it is.

  • subtype"savings_pot" | nullrequired

    savings_pot for a pot inside another account; otherwise null.

  • currencystringrequired

    The account currency, such as GBP.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the accounts:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/accounts \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/accounts/{id}
Needs accounts:read

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

  • idstringrequired

    The account id.

Response fields

  • idstringrequired

    The account id.

  • namestringrequired

    The account name.

  • institutionobjectrequired

    The bank or provider it is held with.

  • institution.idstringrequired

    Its id.

  • institution.namestringrequired

    Its name.

  • kind"current" | "savings" | "credit" | "cash"required

    What sort of account it is.

  • subtype"savings_pot" | nullrequired

    savings_pot for a pot inside another account; otherwise null.

  • currencystringrequired

    The account currency, such as GBP.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the accounts:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/accounts/acc_current \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/institutions
Needs accounts:read

Banks, building societies and the like that hold your accounts, with the ids of the accounts under each (open and closed). To keep a copy in step, send updatedSince: an institution comes back when it, or any account under it, changed since then (closed ones included and flagged).

Query parameters

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

Response fields

  • idstringrequired

    The institution id.

  • namestringrequired

    The institution name.

  • closedbooleanrequired

    True once it has been closed.

  • accountIdsstring[]required

    The ids of its accounts.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the accounts:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/institutions \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/accounts/{id}/balance-checks
Needs accounts:read

The account's most recent balance checks (up to 30), newest first. The ledger figure is recomputed on each read, so a later backdated transaction changes ledger and difference of an old check.

Path parameters

  • idstringrequired

    The account id.

Response fields

  • idstringrequired

    The balance check id.

  • accountIdstringrequired

    The account it was recorded against.

  • observedOnstringrequired

    The UK calendar day the provider balance was read.

  • observedAtstring | nullrequired

    The exact moment, when it was recorded (older checks have only the day).

  • matchesbooleanrequired

    True when the provider balance equals the ledger balance.

  • notestring | nullrequired

    A short note added with the check.

  • resolvedbooleanrequired

    True once a difference has been marked as dealt with.

  • resolvedAtstring | nullrequired

    When it was marked resolved, ISO 8601 in UTC.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the accounts:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/accounts/acc_current/balance-checks \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

POST/api/v1/accounts/{id}/balance-checks
Needs accounts:write

Records what your bank or provider showed for the account, so it can be compared with the ledger. The answer includes the ledger balance at that moment and the difference. Send observedAt (a time) or observedOn (a UK day, covering the whole day); neither may be in the future. Recording a check changes no transactions.

Path parameters

  • idstringrequired

    The account id.

Request body (JSON)

  • observedMinorintegerrequired

    The balance the bank or provider showed, in pence. Negative when money is owed.

  • observedOnstring

    The UK day it was read, YYYY-MM-DD, today or earlier. Covers the whole day; prefer observedAt when 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 | null

    A short note.

Response fields

  • idstringrequired

    The balance check id.

  • accountIdstringrequired

    The account it was recorded against.

  • observedOnstringrequired

    The UK calendar day the provider balance was read.

  • observedAtstring | nullrequired

    The exact moment, when it was recorded (older checks have only the day).

  • matchesbooleanrequired

    True when the provider balance equals the ledger balance.

  • notestring | nullrequired

    A short note added with the check.

  • resolvedbooleanrequired

    True once a difference has been marked as dealt with.

  • resolvedAtstring | nullrequired

    When it was marked resolved, ISO 8601 in UTC.

Errors

  • validation_failed400

    Neither observedAt nor observedOn is sent, or the time is in the future. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the accounts:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 201
{
  "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

PATCH/api/v1/accounts/{id}
Needs accounts:write

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

  • idstringrequired

    The account id.

Request body (JSON)

  • namestring

    A new name.

  • closedboolean

    True closes the account; false reopens it. The default cash account cannot be closed.

  • keepAsideboolean

    True leaves the account out of planning cash (Safe to spend, Forecast, Runway). Credit accounts cannot be kept aside.

  • versionstring

    The version you last read, as an alternative to the If-Match header.

Response fields

  • idstringrequired

    The account id.

  • namestringrequired

    The account name.

  • institutionobjectrequired

    The bank or provider it is held with.

  • institution.idstringrequired

    Its id.

  • institution.namestringrequired

    Its name.

  • kind"current" | "savings" | "credit" | "cash"required

    What sort of account it is.

  • subtype"savings_pot" | nullrequired

    savings_pot for a pot inside another account; otherwise null.

  • currencystringrequired

    The account currency, such as GBP.

Errors

  • validation_failed400

    The body is empty, or keepAside is set on a credit account. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the accounts:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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

GET/api/v1/transactions
Needs transactions:read

Transactions newest first, each with its lines and tags. amount is the net of the lines from your side: money out is negative, and a transfer nets to zero. A transaction’s kind is read from all of its lines (a discount line does not turn a purchase into income). minAmountMinor / maxAmountMinor compare the absolute net amount. Filters on category, payee and account match when any line matches; a parent category or payee also matches its subcategories and sub-payees. Use version as the If-Match value when editing. To keep a copy in step, pass updatedSince (the page.asOf of your last run) and upsert what comes back; transactions are hard-deleted, so list ids occasionally to find the missing ones.

Query parameters

  • fromstring

    Earliest date, inclusive. YYYY-MM-DD (a whole UK day) or an ISO 8601 timestamp.

  • tostring

    Latest date, inclusive. YYYY-MM-DD runs to the end of that UK day; a timestamp is that instant.

  • accountIdstring

    A payment source (card, pot or account activity) id, or a financial account id for all of its sources.

  • categoryIdstring

    Only transactions with a line in this category or any category under it (a parent category includes its subcategories, as on the Transactions page).

  • payeeIdstring

    Only transactions with a line for this payee or any payee under it (a parent payee includes its sub-payees).

  • tagIdstring

    Only transactions carrying this tag.

  • kind"expense" | "income" | "transfer"

    Expense, income or transfer, read from all of a transaction’s lines as the app does.

  • minAmountMinorinteger

    Smallest absolute amount in pence, up to 2147483647.

  • maxAmountMinorinteger

    Largest absolute amount in pence, up to 2147483647.

  • qstring

    Text 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"

    true for transactions with documents attached, false for those without. Needs the documents:read scope and a key for all accounts.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check). A transaction counts as changed when its header, any of its lines or its tags were (the same stamp as version); deleting a tag altogether does not move the transactions that had it. Transactions are hard-deleted, so a deleted one never appears. Paging works as usual.

  • include"documents"

    documents adds each transaction’s attached documents (id and title). Needs the documents:read scope and a key for all accounts.

  • limitinteger

    Transactions per page, 1–200 (50 by default).

  • cursorstring

    page.nextCursor from the previous page.

Response fields

  • idstringrequired

    The transaction id.

  • datestringrequired

    The day it happened, YYYY-MM-DD in UK time.

  • atstringrequired

    The moment it happened, ISO 8601 in UTC.

  • descriptionstringrequired

    What the transaction is called.

  • descriptionAutobooleanrequired

    True when the app writes the description from the lines, and rewrites it when they change.

  • notesstring | nullrequired

    Free-text notes.

  • kind"expense" | "income" | "transfer"required

    Whether money went out, came in, or moved between your own accounts.

  • isTransferbooleanrequired

    True for a move between your own accounts.

Errors

  • validation_failed400

    from is after to, minAmountMinor is above maxAmountMinor, or the cursor is not one a previous page gave. A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    hasDocuments is used without the documents:read scope. The key lacks the transactions:read scope; requiredScope names it.

  • forbidden403

    hasDocuments or include=documents is used by a key limited to some accounts (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/transactions?from=2026-10-01&kind=expense&limit=20' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/transactions/lines
Needs transactions:read

One row per ledger line, newest transaction first and each transaction’s lines in the order they were entered, for scripts that want a flat table. Each row names its transaction. Here minAmountMinor / maxAmountMinor compare the line’s own absolute amount, and account, category, payee and text filters match the line itself (a parent category or payee also matches its subcategories and sub-payees).

Query parameters

  • fromstring

    Earliest date, inclusive. YYYY-MM-DD (a whole UK day) or an ISO 8601 timestamp.

  • tostring

    Latest date, inclusive. YYYY-MM-DD runs to the end of that UK day; a timestamp is that instant.

  • accountIdstring

    A payment source (card, pot or account activity) id, or a financial account id for all of its sources.

  • categoryIdstring

    Only transactions with a line in this category or any category under it (a parent category includes its subcategories, as on the Transactions page).

  • payeeIdstring

    Only transactions with a line for this payee or any payee under it (a parent payee includes its sub-payees).

  • tagIdstring

    Only transactions carrying this tag.

  • kind"expense" | "income" | "transfer"

    Expense, income or transfer, read from all of a transaction’s lines as the app does.

  • minAmountMinorinteger

    Smallest absolute amount in pence, up to 2147483647.

  • maxAmountMinorinteger

    Largest absolute amount in pence, up to 2147483647.

  • qstring

    Text 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"

    true for transactions with documents attached, false for those without. Needs the documents:read scope and a key for all accounts.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check). A line counts as changed when it or its transaction’s header was. Deleted lines never appear.

  • limitinteger

    Lines per page, 1–200 (50 by default).

  • cursorstring

    page.nextCursor from the previous page.

Response fields

  • idstringrequired

    The line id.

  • accountobjectrequired

    The account this line moves money in or out of. For a key limited to some accounts, a line on another account shows { "id": null, "name": "Another account" }.

  • account.idstring | nullrequired

    Its id; null for another account, to a key limited to some accounts.

  • account.namestringrequired

    Its name.

  • amountMinorintegerrequired

    Amount of this line in pence; negative is money out.

  • amountDisplaystringrequired

    Amount of this line ready to show, such as -£12.50.

  • kind"item" | "adjustment" | "surcharge"required

    item is something bought; adjustment a discount or correction; surcharge a fee or tip.

  • categoryobject | nullrequired

    The line's category, or null when it has none.

Errors

  • validation_failed400

    from is after to, minAmountMinor is above maxAmountMinor, or the cursor is not one a previous page gave. A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    hasDocuments is used without the documents:read scope. The key lacks the transactions:read scope; requiredScope names it.

  • forbidden403

    hasDocuments or include=documents is used by a key limited to some accounts (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/transactions/lines?from=2026-10-01&limit=20' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/transactions/{id}
Needs transactions:read

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

  • idstringrequired

    The transaction id.

Response fields

  • idstringrequired

    The transaction id.

  • datestringrequired

    The day it happened, YYYY-MM-DD in UK time.

  • atstringrequired

    The moment it happened, ISO 8601 in UTC.

  • descriptionstringrequired

    What the transaction is called.

  • descriptionAutobooleanrequired

    True when the app writes the description from the lines, and rewrites it when they change.

  • notesstring | nullrequired

    Free-text notes.

  • kind"expense" | "income" | "transfer"required

    Whether money went out, came in, or moved between your own accounts.

  • isTransferbooleanrequired

    True for a move between your own accounts.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the transactions:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/transactions/txn_1 \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

POST/api/v1/transactions
Needs transactions:write

Posts a transaction to the ledger, as if you had entered it in the app. Send lines (each with non-negative amountMinor, including zero; the kind decides whether money goes out or in), or for one line the shorthand accountId + amountMinor + categoryId + payeeId. A transfer takes fromAccountId, toAccountId and amountMinor and is filed under the Transfer category and payee. date is a YYYY-MM-DD day (stored at midday UK time) or an ISO 8601 timestamp. Every expense or income line needs a category and a payee. Send an Idempotency-Key header to make a retry safe: the ledger itself ignores a second post with the same key. Answers 201 with the transaction, including its version for later edits.

Request body (JSON)

  • datestringrequired

    The transaction’s date: YYYY-MM-DD (stored at midday UK time on that day) or an ISO 8601 timestamp for an exact moment.

  • descriptionstring

    What the transaction was, such as Weekly shop. Leave it out and the app writes one from the lines, such as Bought 3 items at Corner Market for £43.50, and keeps it up to date.

  • 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) or smart (long when it fits in 60 characters). Defaults to your Settings choice.

  • descriptionShowAmountboolean

    For a description the app writes: whether it includes the amount. Defaults to your Settings choice.

  • notesstring | null

    Private notes on the transaction; null clears them.

  • kind"expense" | "income" | "transfer"required

    expense takes money out, income puts money in, transfer moves 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.

  • accountIdstring

    Single-line shorthand instead of lines. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.

  • amountMinorinteger

    Single-line shorthand: the amount in pence (zero allowed). For a transfer, the amount moved.

  • categoryIdstring

    Single-line shorthand: the category.

  • payeeIdstring

    Single-line shorthand: the payee.

  • fromAccountIdstring

    Transfers only: where the money leaves. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.

  • toAccountIdstring

    Transfers only: where the money arrives. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.

Response fields

  • idstringrequired

    The transaction id.

  • datestringrequired

    The day it happened, YYYY-MM-DD in UK time.

  • atstringrequired

    The moment it happened, ISO 8601 in UTC.

  • descriptionstringrequired

    What the transaction is called.

  • descriptionAutobooleanrequired

    True when the app writes the description from the lines, and rewrites it when they change.

  • notesstring | nullrequired

    Free-text notes.

  • kind"expense" | "income" | "transfer"required

    Whether money went out, came in, or moved between your own accounts.

  • isTransferbooleanrequired

    True for a move between your own accounts.

Errors

  • validation_failed400

    The lines do not add up, an expense or income line has no category or payee, or a transfer goes to the same account. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    An account, category, payee or tag in the body does not exist or belongs to someone else.

  • idempotency_conflict422

    The ledger already holds a post under this Idempotency-Key for a different transaction. The Idempotency-Key was already used with a different request.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit).

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • forbidden_scope403

    The key lacks the transactions:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 201
{
  "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

PATCH/api/v1/transactions/{id}
Needs transactions:write

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

  • idstringrequired

    The transaction id.

Request body (JSON)

  • datestring

    The transaction’s date: YYYY-MM-DD (stored at midday UK time on that day) or an ISO 8601 timestamp for an exact moment.

  • descriptionstring | null

    A new description; null hands 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) or smart (long when it fits in 60 characters). Defaults to your Settings choice.

  • descriptionShowAmountboolean

    For a description the app writes: whether it includes the amount. Defaults to your Settings choice.

  • notesstring | null

    Private notes on the transaction; null clears 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 id keeps that saved line; one without is added; a saved line left out is removed.

  • accountIdstring

    Single-line shorthand instead of lines. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.

  • amountMinorinteger

    Single-line shorthand: the amount in pence (zero allowed). For a transfer, the amount moved.

  • categoryIdstring

    Single-line shorthand: the category.

  • payeeIdstring

    Single-line shorthand: the payee.

  • fromAccountIdstring

    Transfers only: where the money leaves. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.

  • toAccountIdstring

    Transfers only: where the money arrives. A payment source id (card, pot or account activity), or a financial account id to use its Direct source.

  • versionstring | number

    The version from your last read, as an alternative to the If-Match header.

Response fields

  • idstringrequired

    The transaction id.

  • datestringrequired

    The day it happened, YYYY-MM-DD in UK time.

  • atstringrequired

    The moment it happened, ISO 8601 in UTC.

  • descriptionstringrequired

    What the transaction is called.

  • descriptionAutobooleanrequired

    True when the app writes the description from the lines, and rewrites it when they change.

  • notesstring | nullrequired

    Free-text notes.

  • kind"expense" | "income" | "transfer"required

    Whether money went out, came in, or moved between your own accounts.

  • isTransferbooleanrequired

    True for a move between your own accounts.

Errors

  • validation_failed400

    The body is empty, a line id is not one of this transaction's lines, or kind changes without lines. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    A category, payee, account or tag in the body does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit).

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the transactions:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
      }
    ]
  }'
Response 200
{
  "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

PUT/api/v1/transactions/{id}/tags
Needs transactions:write

Replaces the transaction’s tags with exactly the ones in tagIds (an empty list removes them all). A change of tags is a change to the transaction: its updatedAt and version move on, so updatedSince finds it. Answers with the transaction.

Path parameters

  • idstringrequired

    The transaction id.

Request body (JSON)

  • tagIdsstring[]required

    Tag ids. The transaction ends up with exactly these tags.

  • versionstring | number

    The version from your last read, as an alternative to the If-Match header.

Response fields

  • idstringrequired

    The transaction id.

  • datestringrequired

    The day it happened, YYYY-MM-DD in UK time.

  • atstringrequired

    The moment it happened, ISO 8601 in UTC.

  • descriptionstringrequired

    What the transaction is called.

  • descriptionAutobooleanrequired

    True when the app writes the description from the lines, and rewrites it when they change.

  • notesstring | nullrequired

    Free-text notes.

  • kind"expense" | "income" | "transfer"required

    Whether money went out, came in, or moved between your own accounts.

  • isTransferbooleanrequired

    True for a move between your own accounts.

Errors

  • validation_failed400

    A tag id in tagIds is not one of your tags. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit).

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the transactions:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
    ]
  }'
Response 200
{
  "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

DELETE/api/v1/transactions/{id}
Needs transactions:delete

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

  • idstringrequired

    The transaction id.

Query parameters

  • documents"keep" | "delete"

    keep (the default) leaves attached documents unfiled; delete moves documents attached only to this transaction to the trash.

Errors

  • conflict409

    The transaction has linked refunds or chargebacks (reason: has_linked_refunds), or is an account's opening balance (reason: opening_balance).

  • forbidden_scope403

    documents=delete is sent without the documents:delete scope. The key lacks the transactions:delete scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit). documents=delete is sent by a key limited to some accounts (reason: account_limit).

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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

POST/api/v1/transactions/batch
Needs transactions:write

Posts 1–100 transactions in one call. Each item in transactions is exactly the body of POST /transactions. The batch is all or nothing: if any item is invalid, or the ledger refuses it, nothing is created and the 400 names the item in details (for example body.transactions.3.amountMinor). Answers 201 with the created transactions in the order you sent them. Send an Idempotency-Key header to make a retry safe: the same key with the same batch answers the first result again, and the ledger itself ignores a second post of any item under its key. The call counts once against the rate limit. For a key limited to some accounts, an item that names another account refuses the whole batch with a 403 naming the item.

Request body (JSON)

  • transactionsobject[]required

    1–100 transactions, each exactly the body of POST /transactions.

Response fields

  • idstringrequired

    The transaction id.

  • datestringrequired

    The day it happened, YYYY-MM-DD in UK time.

  • atstringrequired

    The moment it happened, ISO 8601 in UTC.

  • descriptionstringrequired

    What the transaction is called.

  • descriptionAutobooleanrequired

    True when the app writes the description from the lines, and rewrites it when they change.

  • notesstring | nullrequired

    Free-text notes.

  • kind"expense" | "income" | "transfer"required

    Whether money went out, came in, or moved between your own accounts.

  • isTransferbooleanrequired

    True for a move between your own accounts.

Errors

  • forbidden403

    The key is limited to some accounts and an item names another one; nothing is created and details names the item (reason: account_limit).

  • validation_failed400

    A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the transactions:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
      }
    ]
  }'
Response 201
{
  "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

GET/api/v1/transactions/export
Needs transactions:read

A CSV file of your transactions, one row per ledger line, newest first, with the same filters as GET /transactions (from, to, accountId, categoryId, payeeId, tagId, kind, q, amounts). Columns: date, transactionId, description, kind, account, category, payee, tags (names, ; -separated), amount (pounds as a plain decimal, negative when money goes out), amountMinor (pence), currency and notes (the line’s note). Text that a spreadsheet would read as a formula starts with ' so it opens as text. A file holds at most 10,000 lines: if more match, the answer is a 400 asking you to narrow the dates. Answers text/csv as an attachment named transactions-YYYY-MM-DD.csv, not the usual JSON envelope. A key limited to some accounts gets the transactions on its accounts, with a line on another account (the other side of a transfer) under Another account.

Query parameters

  • fromstring

    Earliest date, inclusive. YYYY-MM-DD (a whole UK day) or an ISO 8601 timestamp.

  • tostring

    Latest date, inclusive. YYYY-MM-DD runs to the end of that UK day; a timestamp is that instant.

  • accountIdstring

    A payment source (card, pot or account activity) id, or a financial account id for all of its sources.

  • categoryIdstring

    Only transactions with a line in this category or any category under it (a parent category includes its subcategories, as on the Transactions page).

  • payeeIdstring

    Only transactions with a line for this payee or any payee under it (a parent payee includes its sub-payees).

  • tagIdstring

    Only transactions carrying this tag.

  • kind"expense" | "income" | "transfer"

    Expense, income or transfer, read from all of a transaction’s lines as the app does.

  • minAmountMinorinteger

    Smallest absolute amount in pence, up to 2147483647.

  • maxAmountMinorinteger

    Largest absolute amount in pence, up to 2147483647.

  • qstring

    Text 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"

    true for transactions with documents attached, false for those without. Needs the documents:read scope and a key for all accounts.

  • format"csv"

    The file format. Only csv for now.

Errors

  • validation_failed400

    More lines match than one file holds; narrow the dates. A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    hasDocuments is used without the documents:read scope. The key lacks the transactions:read scope; requiredScope names it.

  • forbidden403

    hasDocuments or include=documents is used by a key limited to some accounts (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/transactions/export?from=2026-10-01&to=2026-10-31' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
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

GET/api/v1/categories
Needs categories:read

Every category in the order the app shows them (sort order, then name). Categories nest: parentId is the group a category sits in, so the whole tree comes back in one page. To keep a copy in step, send updatedSince: only categories changed since then come back, archived ones included and flagged.

Query parameters

  • archived"exclude" | "include" | "only"

    Archived items: exclude (default), include or only. With updatedSince the default is include, so a change to archived shows.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

Response fields

  • idstringrequired

    The category id.

  • namestringrequired

    The category name.

  • parentIdstring | nullrequired

    The parent category, for a category inside a group; null at the top.

  • systemKeystring | nullrequired

    Set on the categories the app itself relies on, such as starting balance.

  • iconstring | nullrequired

    The icon name, if one is set.

  • colorstring | nullrequired

    The colour as a hex code, if one is set.

  • notesstring | nullrequired

    Free-text notes about what belongs in this category; null when none are set.

  • sortOrderintegerrequired

    Position among its siblings; lower comes first.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the categories:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/categories?archived=exclude' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/categories/{id}
Needs categories:read

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

  • idstringrequired

    The category id.

Response fields

  • idstringrequired

    The category id.

  • namestringrequired

    The category name.

  • parentIdstring | nullrequired

    The parent category, for a category inside a group; null at the top.

  • systemKeystring | nullrequired

    Set on the categories the app itself relies on, such as starting balance.

  • iconstring | nullrequired

    The icon name, if one is set.

  • colorstring | nullrequired

    The colour as a hex code, if one is set.

  • notesstring | nullrequired

    Free-text notes about what belongs in this category; null when none are set.

  • sortOrderintegerrequired

    Position among its siblings; lower comes first.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the categories:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/categories/cat_1 \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/rules
Needs categories:read

The rules that file new transactions and wallet purchases, highest priority first. matchDescription is the conditions in words; payee, account and amountMatch give them in parts. Amounts are pence (amountMinor, and amountMaxMinor for a range) in the absolute value of the transaction. To keep a copy in step, send updatedSince: only rules changed since then come back, archived ones included and flagged.

Query parameters

  • archived"exclude" | "include" | "only"

    Archived items: exclude (default), include or only. With updatedSince the default is include, so a change to archived shows.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

Response fields

  • idstringrequired

    The rule id.

  • namestringrequired

    The rule name.

  • priorityintegerrequired

    Higher numbers win when two rules set the same field.

  • enabledbooleanrequired

    False while the rule is switched off.

  • applyMode"suggest" | "auto_apply" | nullrequired

    Null follows the default in Settings.

  • autoApproveTrustedbooleanrequired

    Whether the rule also approves matching items it trusts without asking.

  • matchDescriptionstringrequired

    The conditions in words, as the Rules page shows them.

  • payeeobject | nullrequired

    The payee the rule matches, or null when it does not match on payee.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the categories:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/rules?archived=exclude' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

POST/api/v1/categories
Needs categories:write

Creates a category, optionally inside another one. Answers 409 conflict when a category with that name already exists under the same parent.

Request body (JSON)

  • namestringrequired

    The category name. Names are unique among categories with the same parent.

  • parentIdstring | null

    The 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" | null

    An icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag. Null clears it.

  • colorstring | null

    A six-digit hex colour such as #cc2936. Null clears it.

  • notesstring | null

    Free-text notes about what belongs in this category. Null or blank clears them.

Response fields

  • idstringrequired

    The category id.

  • namestringrequired

    The category name.

  • parentIdstring | nullrequired

    The parent category, for a category inside a group; null at the top.

  • systemKeystring | nullrequired

    Set on the categories the app itself relies on, such as starting balance.

  • iconstring | nullrequired

    The icon name, if one is set.

  • colorstring | nullrequired

    The colour as a hex code, if one is set.

  • notesstring | nullrequired

    Free-text notes about what belongs in this category; null when none are set.

  • sortOrderintegerrequired

    Position among its siblings; lower comes first.

Errors

  • conflict409

    A category with that name already exists under the same parent.

  • not_found404

    The parentId does not exist or belongs to someone else.

  • validation_failed400

    A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the categories:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 201
{
  "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

PATCH/api/v1/categories/{id}
Needs categories:write

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

  • idstringrequired

    The category id.

Request body (JSON)

  • namestring

    A new name.

  • parentIdstring | null

    Move 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" | null

    An icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag. Null clears it.

  • colorstring | null

    A six-digit hex colour such as #cc2936. Null clears it.

  • notesstring | null

    Free-text notes about what belongs in this category. Null or blank clears them.

  • archivedboolean

    True archives the category and every category inside it; false restores just this one.

  • versionstring

    The version you last read, as an alternative to the If-Match header.

Response fields

  • idstringrequired

    The category id.

  • namestringrequired

    The category name.

  • parentIdstring | nullrequired

    The parent category, for a category inside a group; null at the top.

  • systemKeystring | nullrequired

    Set on the categories the app itself relies on, such as starting balance.

  • iconstring | nullrequired

    The icon name, if one is set.

  • colorstring | nullrequired

    The colour as a hex code, if one is set.

  • notesstring | nullrequired

    Free-text notes about what belongs in this category; null when none are set.

  • sortOrderintegerrequired

    Position among its siblings; lower comes first.

Errors

  • validation_failed400

    The body is empty, or a system category is being archived. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • conflict409

    Another category under the same parent already has that name.

  • not_found404

    The parentId does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the categories:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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

GET/api/v1/payees
Needs payees:read

Payees by name. q finds payees whose name contains the text, ignoring case. parent is the payee a branch belongs to; defaultCategory is the category new transactions for this payee start with. To keep a copy in step, send updatedSince: only payees changed since then come back, archived ones included and flagged. A connected app gets only the payees on income it can read: who pays in, never who you pay.

Query parameters

  • archived"exclude" | "include" | "only"

    Archived items: exclude (default), include or only. With updatedSince the default is include, so a change to archived shows.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

  • qstring

    Only payees whose name contains this text.

  • limitinteger

    Payees per page, 1–200 (50 by default).

  • cursorstring

    page.nextCursor from the previous page.

Response fields

  • idstringrequired

    The payee id.

  • namestringrequired

    The payee name.

  • kind"general" | "physical" | "online"required

    general for any payee, physical for a shop with locations, online for a web shop.

  • transactionType"expense" | "income" | "both"required

    What the payee is used for.

  • parentobject | nullrequired

    The payee this one is a branch of.

  • parent.idstringrequired

    Its id.

  • parent.namestringrequired

    Its name.

  • defaultCategoryobject | nullrequired

    The category new transactions with this payee start with, or null.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the payees:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/payees?q=market&limit=20' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/payees/{id}
Needs payees:read

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

  • idstringrequired

    The payee id.

Response fields

  • idstringrequired

    The payee id.

  • namestringrequired

    The payee name.

  • kind"general" | "physical" | "online"required

    general for any payee, physical for a shop with locations, online for a web shop.

  • transactionType"expense" | "income" | "both"required

    What the payee is used for.

  • parentobject | nullrequired

    The payee this one is a branch of.

  • parent.idstringrequired

    Its id.

  • parent.namestringrequired

    Its name.

  • defaultCategoryobject | nullrequired

    The category new transactions with this payee start with, or null.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the payees:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/payees/pay_1 \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

POST/api/v1/payees
Needs payees:write

Creates a payee. transactionType defaults to both. Answers 409 conflict when a payee with that name already exists under the same parent.

Request body (JSON)

  • namestringrequired

    The payee name. Names are unique among payees with the same parent.

  • kind"general" | "physical" | "online"

    general (the default), physical (a shop or branch) or online.

  • transactionType"expense" | "income" | "both"

    What the payee is used for. Defaults to both when creating.

  • parentIdstring | null

    The payee this one is a branch of. Null makes it top-level.

  • defaultCategoryIdstring | null

    The 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" | null

    An icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag.

  • colorstring | null

    A six-digit hex colour such as #cc2936.

  • websiteUrlstring | null

    An https:// address without credentials.

  • notesstring | null

    Free text.

Response fields

  • idstringrequired

    The payee id.

  • namestringrequired

    The payee name.

  • kind"general" | "physical" | "online"required

    general for any payee, physical for a shop with locations, online for a web shop.

  • transactionType"expense" | "income" | "both"required

    What the payee is used for.

  • parentobject | nullrequired

    The payee this one is a branch of.

  • parent.idstringrequired

    Its id.

  • parent.namestringrequired

    Its name.

  • defaultCategoryobject | nullrequired

    The category new transactions with this payee start with, or null.

Errors

  • conflict409

    A payee with that name already exists under the same parent.

  • not_found404

    The parentId or defaultCategoryId does not exist or belongs to someone else.

  • validation_failed400

    A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the payees:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 201
{
  "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

PATCH/api/v1/payees/{id}
Needs payees:write

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

  • idstringrequired

    The payee id.

Request body (JSON)

  • namestring

    A new name.

  • kind"general" | "physical" | "online"

    general (the default), physical (a shop or branch) or online.

  • transactionType"expense" | "income" | "both"

    What the payee is used for. Defaults to both when creating.

  • parentIdstring | null

    The payee this one is a branch of. Null makes it top-level.

  • defaultCategoryIdstring | null

    The 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" | null

    An icon from the app's set: store, building, user, globe, shopping-cart, coffee, utensils, home, car, train, heart, briefcase, gift, wallet, tag.

  • colorstring | null

    A six-digit hex colour such as #cc2936.

  • websiteUrlstring | null

    An https:// address without credentials.

  • notesstring | null

    Free text.

  • archivedboolean

    True archives the payee (its sub-payees must be archived first); false restores it.

  • versionstring

    The version you last read, as an alternative to the If-Match header.

Response fields

  • idstringrequired

    The payee id.

  • namestringrequired

    The payee name.

  • kind"general" | "physical" | "online"required

    general for any payee, physical for a shop with locations, online for a web shop.

  • transactionType"expense" | "income" | "both"required

    What the payee is used for.

  • parentobject | nullrequired

    The payee this one is a branch of.

  • parent.idstringrequired

    Its id.

  • parent.namestringrequired

    Its name.

  • defaultCategoryobject | nullrequired

    The category new transactions with this payee start with, or null.

Errors

  • validation_failed400

    The body is empty, a payee is archived while its branches are not, or one is restored under an archived parent. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • conflict409

    Another payee under the same parent has that name, or kind changes on a payee that already has transactions.

  • not_found404

    The parentId or defaultCategoryId does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the payees:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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"
  }
}

Tags

5 endpoints

List tags

GET/api/v1/tags
Needs tags:read

Every tag by name, with how many transactions carry it. Use a tag’s id as tagId on /transactions. To keep a copy in step, send updatedSince: only tags renamed or created since then come back. Tags are hard-deleted, so a deleted tag does not appear (list the ids to find it), and tagging a transaction changes transactionCount without making the tag count as changed. Every tag is listed for a key limited to some accounts too, but transactionCount only counts the transactions it can list.

Query parameters

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

Response fields

  • idstringrequired

    The tag id.

  • namestringrequired

    The tag name.

  • transactionCountintegerrequired

    How many transactions carry the tag (for a key limited to some accounts, how many of those it can list).

  • createdAtstring | nullrequired

    When it was created, ISO 8601 in UTC.

  • updatedAtstring | nullrequired

    When it last changed, ISO 8601 in UTC.

  • versionstringrequired

    Send as If-Match when editing or deleting it, to avoid overwriting a newer change.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the tags:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/tags \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "data": [
    {
      "id": "tag_1",
      "name": "Household",
      "transactionCount": 14,
      "createdAt": "2026-02-01T09:00:00.000Z",
      "updatedAt": "2026-02-01T09:00:00.000Z",
      "version": "1769936400000"
    }
  ],
  "page": {
    "nextCursor": null,
    "hasMore": false,
    "asOf": "2026-10-26T09:00:00.000Z"
  }
}

Get a tag

GET/api/v1/tags/{id}
Needs tags:read

One tag by id, with how many transactions carry it, and the version to send as If-Match when renaming or deleting it (also sent as the ETag header). Another user's id answers 404, the same as an id that does not exist.

Path parameters

  • idstringrequired

    The tag id.

Response fields

  • idstringrequired

    The tag id.

  • namestringrequired

    The tag name.

  • transactionCountintegerrequired

    How many transactions carry the tag (for a key limited to some accounts, how many of those it can list).

  • createdAtstring | nullrequired

    When it was created, ISO 8601 in UTC.

  • updatedAtstring | nullrequired

    When it last changed, ISO 8601 in UTC.

  • versionstringrequired

    Send as If-Match when editing or deleting it, to avoid overwriting a newer change.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the tags:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/tags/tag_1 \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "data": {
    "id": "tag_1",
    "name": "Household",
    "transactionCount": 14,
    "createdAt": "2026-02-01T09:00:00.000Z",
    "updatedAt": "2026-02-01T09:00:00.000Z",
    "version": "1769936400000"
  }
}

Create a tag

POST/api/v1/tags
Needs tags:write

Creates a tag. Answers 409 conflict when a tag with that name already exists.

Request body (JSON)

  • namestringrequired

    The tag name, up to 80 characters. Names are unique, ignoring case.

Response fields

  • idstringrequired

    The tag id.

  • namestringrequired

    The tag name.

  • transactionCountintegerrequired

    How many transactions carry the tag (for a key limited to some accounts, how many of those it can list).

  • createdAtstring | nullrequired

    When it was created, ISO 8601 in UTC.

  • updatedAtstring | nullrequired

    When it last changed, ISO 8601 in UTC.

  • versionstringrequired

    Send as If-Match when editing or deleting it, to avoid overwriting a newer change.

Errors

  • conflict409

    A tag with that name already exists (names compare without regard to case).

  • validation_failed400

    A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the tags:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl -X POST https://finance.jagwebsites.xyz/api/v1/tags \
  -H 'Authorization: Bearer sk_your_key' \
  -H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Household"
  }'
Response 201
{
  "data": {
    "id": "tag_1",
    "name": "Household",
    "transactionCount": 0,
    "createdAt": "2026-02-01T09:00:00.000Z",
    "updatedAt": "2026-02-01T09:00:00.000Z",
    "version": "1769936400000"
  }
}

Rename a tag

PATCH/api/v1/tags/{id}
Needs tags:write

Renames the tag; every transaction that carries it follows. Send the version you last read as If-Match (or in the body): if the tag has changed since, the answer is 412 version_conflict.

Path parameters

  • idstringrequired

    The tag id.

Request body (JSON)

  • namestringrequired

    The tag name, up to 80 characters. Names are unique, ignoring case.

  • versionstring

    The version you last read, as an alternative to the If-Match header.

Response fields

  • idstringrequired

    The tag id.

  • namestringrequired

    The tag name.

  • transactionCountintegerrequired

    How many transactions carry the tag (for a key limited to some accounts, how many of those it can list).

  • createdAtstring | nullrequired

    When it was created, ISO 8601 in UTC.

  • updatedAtstring | nullrequired

    When it last changed, ISO 8601 in UTC.

  • versionstringrequired

    Send as If-Match when editing or deleting it, to avoid overwriting a newer change.

Errors

  • conflict409

    Another tag already has that name.

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • validation_failed400

    A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the tags:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl -X PATCH https://finance.jagwebsites.xyz/api/v1/tags/tag_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": "Home"
  }'
Response 200
{
  "data": {
    "id": "tag_1",
    "name": "Home",
    "transactionCount": 14,
    "createdAt": "2026-02-01T09:00:00.000Z",
    "updatedAt": "2026-02-01T09:00:00.000Z",
    "version": "1769936400000"
  }
}

Delete a tag

DELETE/api/v1/tags/{id}
Needs tags:delete

Deletes the tag and removes it from every transaction and rule that carries it; the transactions and rules themselves are untouched. The API has no undo: for 30 days the tag can be put back in the app, from Settings › Clean Up. Send the version you last read as If-Match to refuse the delete if the tag has changed since (412 version_conflict). A key limited to some accounts may only delete a tag whose transactions are all on its accounts; otherwise the answer is 403 forbidden (reason: account_limit).

Path parameters

  • idstringrequired

    The tag id.

Errors

  • forbidden403

    The key is limited to some accounts and the tag is on a transaction with a line on another one (reason: account_limit).

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the tags:delete scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl -X DELETE https://finance.jagwebsites.xyz/api/v1/tags/tag_1 \
  -H 'Authorization: Bearer sk_your_key' \
  -H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11' \
  -H 'If-Match: "1761480000000"'

204 with no body.

Bills

15 endpoints

What is due soon

GET/api/v1/bills/upcoming
Needs bills:read

Recurring bills and one-off scheduled items merged into one list by due day, the same list as the Upcoming page. Anything overdue is included, however old. Amounts are the size of the payment (always positive); direction says whether it is money out, in or moved. covered says whether the account is projected to hold enough on the day, after everything due before it. The coverage available and shortfall amounts are account balances, so they are null unless the key can also read accounts; covered and the coverage status are always given. Reads the first 500 items due in the window; when more than that fall in it, meta.truncated is true (ask for fewer days).

Query parameters

  • daysinteger

    How many days ahead to look, 1 to 366.

  • limitinteger

    Items per page, 1 to 200.

  • cursorstring

    The nextCursor of the previous page.

Response fields

  • type"recurring" | "scheduled"required

    recurring for an occurrence of a repeating bill, scheduled for a one-off scheduled item.

  • idstringrequired

    The occurrence id (recurring) or the scheduled item id.

  • seriesIdstring | nullrequired

    The recurring series it belongs to; null for a scheduled item.

  • namestringrequired

    What the bill is called.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • dueOnstringrequired

    The day it is due, YYYY-MM-DD.

  • status"pending" | "pre_approved"required

    pending waits for you to post it; pre_approved will be posted on its day.

  • accountobject | nullrequired

    The account the money leaves or arrives in, or null.

Errors

  • validation_failed400

    days is outside 1 to 366, or the cursor is not one a previous page gave. A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the bills:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/bills/upcoming?days=14' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/recurring
Needs bills:read

Recurring series: the bills, subscriptions, income and transfers that repeat. By default the active and paused ones. expectedAmount is the usual size of one payment (positive; direction says which way it goes). To keep a copy in step, send updatedSince: only series changed since then come back, whatever their status, so one that ended shows with status: ended.

Query parameters

  • statusstring

    Comma-separated: active, paused, ended, suggested, dismissed. Default active,paused, or all of them with updatedSince.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

Response fields

  • idstringrequired

    The series id.

  • namestringrequired

    What the series is called.

  • status"active" | "paused" | "ended" | "suggested" | "dismissed"required

    Whether it is running: active, paused, ended, or suggested / dismissed for ones spotted from your transactions.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"required

    How often it repeats.

  • anchorDayintegerrequired

    Weekday (0 = Sunday) for weekly cadences, day of the month otherwise.

  • anchorMonthinteger | nullrequired

    Yearly series only.

  • intervalDaysinteger | nullrequired

    Custom cadence only: every N days.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the bills:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/recurring \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/recurring/{id}
Needs bills:read

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

  • idstringrequired

    The id.

Response fields

  • idstringrequired

    The series id.

  • namestringrequired

    What the series is called.

  • status"active" | "paused" | "ended" | "suggested" | "dismissed"required

    Whether it is running: active, paused, ended, or suggested / dismissed for ones spotted from your transactions.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"required

    How often it repeats.

  • anchorDayintegerrequired

    Weekday (0 = Sunday) for weekly cadences, day of the month otherwise.

  • anchorMonthinteger | nullrequired

    Yearly series only.

  • intervalDaysinteger | nullrequired

    Custom cadence only: every N days.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the bills:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/recurring/ser_1 \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/scheduled
Needs bills:read

One-off payments and income you have scheduled, by due day. By default the ones still to happen (pending and pre-approved); ask for posted or cancelled to see history. amount is the size of the payment (positive; direction says which way). To keep a copy in step, send updatedSince: only items changed since then come back, whatever their status, so one that was posted or cancelled shows with that status.

Query parameters

  • statusstring

    Comma-separated: pending, pre_approved, posted, cancelled. Default pending,pre_approved, or all of them with updatedSince.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

  • limitinteger

    Items per page, 1 to 200.

  • cursorstring

    The nextCursor of the previous page.

Response fields

  • idstringrequired

    The scheduled item id.

  • namestringrequired

    What the item is called.

  • notesstring | nullrequired

    Free-text notes.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • dueOnstringrequired

    The day it is due, YYYY-MM-DD.

  • status"pending" | "pre_approved" | "posted" | "cancelled"required

    Where it has got to: waiting, pre-approved, posted as a transaction or cancelled.

  • accountobject | nullrequired

    The account the money leaves or arrives in, or null.

  • account.idstringrequired

    The payment source id.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the bills:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/scheduled \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/scheduled/{id}
Needs bills:read

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

  • idstringrequired

    The id.

Response fields

  • idstringrequired

    The scheduled item id.

  • namestringrequired

    What the item is called.

  • notesstring | nullrequired

    Free-text notes.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • dueOnstringrequired

    The day it is due, YYYY-MM-DD.

  • status"pending" | "pre_approved" | "posted" | "cancelled"required

    Where it has got to: waiting, pre-approved, posted as a transaction or cancelled.

  • accountobject | nullrequired

    The account the money leaves or arrives in, or null.

  • account.idstringrequired

    The payment source id.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the bills:read scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/scheduled/sch_1 \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

POST/api/v1/scheduled
Needs bills:write

Schedules a payment or income for a day. Nothing is posted to the ledger until the item is posted (POST /scheduled/{id}/post) or, with autoPost, its due day arrives; if autoPost is true and the due day is today or earlier it is posted to the ledger straight away and the answer has its transactionId. Send the amount as positive pence and the direction; a transfer also needs counterAccountId.

Request body (JSON)

  • descriptionstringrequired

    What it is, such as “Car service”. Becomes the transaction description when it posts.

  • dueOnstringrequired

    The day it is due. YYYY-MM-DD.

  • direction"expense" | "income" | "transfer"required

    expense is money out, income money in, transfer between two of your accounts.

  • amountMinorintegerrequired

    The amount in pence, always positive; direction says which way it goes.

  • accountIdstringrequired

    The account the money comes out of (or goes into, for income). A payment source id (the account of a bill), not a financial account id.

  • counterAccountIdstring

    Transfers only, and required for them: the account the money goes into.

  • categoryIdstring

    The category to post it under. Required for an expense or income; a transfer is filed under Transfer.

  • payeeIdstring

    The payee to post it under.

  • notesstring | null

    Free-text notes.

  • autoPostboolean

    Post it to the ledger by itself on the due day (default false). If the due day is today or past, it posts straight away.

  • remindDaysBeforeinteger

    Send a reminder this many days before it is due, 0 to 30.

Response fields

  • idstringrequired

    The scheduled item id.

  • namestringrequired

    What the item is called.

  • notesstring | nullrequired

    Free-text notes.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • dueOnstringrequired

    The day it is due, YYYY-MM-DD.

  • status"pending" | "pre_approved" | "posted" | "cancelled"required

    Where it has got to: waiting, pre-approved, posted as a transaction or cancelled.

  • accountobject | nullrequired

    The account the money leaves or arrives in, or null.

  • account.idstringrequired

    The payment source id.

Errors

  • validation_failed400

    A transfer has no counterAccountId, or an expense or income has no categoryId. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    An account, category or payee in the body does not exist or belongs to someone else.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit).

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 201
{
  "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

PATCH/api/v1/scheduled/{id}
Needs bills:write

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

  • idstringrequired

    The id.

Request body (JSON)

  • descriptionstring

    A new description.

  • dueOnstring

    A new due day. YYYY-MM-DD.

  • amountMinorinteger

    A new amount in pence, always positive.

  • accountIdstring

    A new account. A payment source id (the account of a bill), not a financial account id.

  • counterAccountIdstring

    Transfers only: a new account the money goes into.

  • categoryIdstring | null

    A new category. Null clears it.

  • payeeIdstring | null

    A new payee. Null clears it.

  • notesstring | null

    New notes. Null clears them.

  • autoPostboolean

    Turn automatic posting on or off.

  • remindDaysBeforeinteger

    Send a reminder this many days before it is due, 0 to 30.

  • versionstring | integer

    The version you last read. The same as sending If-Match; if the item has changed since, the answer is 412.

Response fields

  • idstringrequired

    The scheduled item id.

  • namestringrequired

    What the item is called.

  • notesstring | nullrequired

    Free-text notes.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • dueOnstringrequired

    The day it is due, YYYY-MM-DD.

  • status"pending" | "pre_approved" | "posted" | "cancelled"required

    Where it has got to: waiting, pre-approved, posted as a transaction or cancelled.

  • accountobject | nullrequired

    The account the money leaves or arrives in, or null.

  • account.idstringrequired

    The payment source id.

Errors

  • validation_failed400

    The body is empty, or the item is already posted or cancelled. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • conflict409

    The item is split across several lines (reason: multiple_lines), so it cannot be changed field by field.

  • not_found404

    An account, category or payee in the body does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit).

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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

POST/api/v1/scheduled/{id}/post
Needs bills:write

Posts the item now, even before its due day, as a real transaction. The answer is the scheduled item, now posted, with the new transactionId. Send amountMinor or date to post a different amount or date than scheduled (the amount only on a plain, single-line item). An item that is already posted or cancelled cannot be posted.

Path parameters

  • idstringrequired

    The id.

Request body (JSON)

  • datestring

    The transaction date to post it under (default: the day it was scheduled for). YYYY-MM-DD.

  • amountMinorinteger

    Post a different amount (in pence, positive) than the one scheduled.

Response fields

  • idstringrequired

    The scheduled item id.

  • namestringrequired

    What the item is called.

  • notesstring | nullrequired

    Free-text notes.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • dueOnstringrequired

    The day it is due, YYYY-MM-DD.

  • status"pending" | "pre_approved" | "posted" | "cancelled"required

    Where it has got to: waiting, pre-approved, posted as a transaction or cancelled.

  • accountobject | nullrequired

    The account the money leaves or arrives in, or null.

  • account.idstringrequired

    The payment source id.

Errors

  • validation_failed400

    The item is already posted or cancelled. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • conflict409

    amountMinor is sent for an item with several lines (reason: multiple_lines); post it as scheduled, or change it in the app.

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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

POST/api/v1/scheduled/{id}/cancel
Needs bills:delete

Cancels an item that has not been posted, so it no longer shows as upcoming. Nothing is removed from the ledger and the item stays readable with status cancelled. Cancelling an item that is already cancelled changes nothing; a posted item cannot be cancelled.

Path parameters

  • idstringrequired

    The id.

Response fields

  • idstringrequired

    The scheduled item id.

  • namestringrequired

    What the item is called.

  • notesstring | nullrequired

    Free-text notes.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • dueOnstringrequired

    The day it is due, YYYY-MM-DD.

  • status"pending" | "pre_approved" | "posted" | "cancelled"required

    Where it has got to: waiting, pre-approved, posted as a transaction or cancelled.

  • accountobject | nullrequired

    The account the money leaves or arrives in, or null.

  • account.idstringrequired

    The payment source id.

Errors

  • validation_failed400

    The item has already been posted.

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:delete scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 200
{
  "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

POST/api/v1/recurring
Needs bills:write

Creates a repeating series and its upcoming occurrences (nothing is posted to the ledger). Say when it repeats with cadence and either startOn (the first due day; the weekday or day of the month is taken from it) or an explicit anchorDay. A custom cadence needs intervalDays; a transfer needs counterAccountId. A category is required (except for a transfer); set a payee too so occurrences can be posted.

Request body (JSON)

  • namestringrequired

    What it is, such as “Broadband”.

  • direction"expense" | "income" | "transfer"

    expense (the default), income or transfer.

  • cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"required

    How often it repeats.

  • anchorDayinteger

    Weekday (0 = Sunday to 6) for weekly, fortnightly and four-weekly cadences; day of the month (1 to 31) for the rest. Worked out from startOn when left out.

  • anchorMonthinteger | null

    Yearly cadence only: the month, 1 to 12. Worked out from startOn when left out.

  • intervalDaysinteger | null

    Custom cadence only, and required for it: repeat every this many days.

  • startOnstring

    The first day it can fall due (default today). Its first due day is the first one on or after this. YYYY-MM-DD.

  • expectedAmountMinorintegerrequired

    The usual amount of one payment, in pence, always positive.

  • accountIdstringrequired

    The account it is paid from (or into, for income). A payment source id (the account of a bill), not a financial account id.

  • counterAccountIdstring

    Transfers only, and required for them: the account the money goes into.

  • categoryIdstring

    The category payments are posted under. Required for an expense or income; a transfer is filed under Transfer.

  • payeeIdstring

    The payee payments are posted under. Needed before an occurrence can be posted.

  • remindDaysBeforeinteger

    Remind this many days before each is due, 0 to 30 (default 3).

  • notesstring | null

    Free-text notes.

Response fields

  • idstringrequired

    The series id.

  • namestringrequired

    What the series is called.

  • status"active" | "paused" | "ended" | "suggested" | "dismissed"required

    Whether it is running: active, paused, ended, or suggested / dismissed for ones spotted from your transactions.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"required

    How often it repeats.

  • anchorDayintegerrequired

    Weekday (0 = Sunday) for weekly cadences, day of the month otherwise.

  • anchorMonthinteger | nullrequired

    Yearly series only.

  • intervalDaysinteger | nullrequired

    Custom cadence only: every N days.

Errors

  • validation_failed400

    A custom cadence has no intervalDays, a transfer has no counterAccountId, or an expense or income has no categoryId. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    An account, category or payee in the body does not exist or belongs to someone else.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit).

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 201
{
  "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

PATCH/api/v1/recurring/{id}
Needs bills:write

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

  • idstringrequired

    The id.

Request body (JSON)

  • namestring

    A 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).

  • anchorDayinteger

    Weekday (0 = Sunday to 6) for weekly, fortnightly and four-weekly cadences; day of the month (1 to 31) for the rest. Worked out from startOn when left out.

  • anchorMonthinteger | null

    Yearly cadence only: the month, 1 to 12. Worked out from startOn when left out.

  • intervalDaysinteger | null

    Custom cadence only, and required for it: repeat every this many days.

  • expectedAmountMinorinteger

    A new usual amount in pence, always positive. Applies to occurrences not yet customised.

  • accountIdstring

    A new account. A payment source id (the account of a bill), not a financial account id.

  • counterAccountIdstring | null

    Transfers only: a new account the money goes into.

  • categoryIdstring | null

    A new default category. Null clears it.

  • payeeIdstring | null

    A new default payee. Null clears it.

  • remindDaysBeforeinteger

    Send a reminder this many days before it is due, 0 to 30.

  • notesstring | null

    New notes. Null clears them.

  • versionstring | integer

    The version you last read. The same as sending If-Match; if the item has changed since, the answer is 412.

Response fields

  • idstringrequired

    The series id.

  • namestringrequired

    What the series is called.

  • status"active" | "paused" | "ended" | "suggested" | "dismissed"required

    Whether it is running: active, paused, ended, or suggested / dismissed for ones spotted from your transactions.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"required

    How often it repeats.

  • anchorDayintegerrequired

    Weekday (0 = Sunday) for weekly cadences, day of the month otherwise.

  • anchorMonthinteger | nullrequired

    Yearly series only.

  • intervalDaysinteger | nullrequired

    Custom cadence only: every N days.

Errors

  • validation_failed400

    The body is empty, the series has ended or been dismissed, or customised or pre-approved occurrences block a schedule change. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    An account, category or payee in the body does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit).

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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

POST/api/v1/recurring/{id}/pause
Needs bills:write

Stops an active series from falling due until it is resumed. Nothing is removed and nothing is posted. Pausing a series that is already paused changes nothing.

Path parameters

  • idstringrequired

    The id.

Response fields

  • idstringrequired

    The series id.

  • namestringrequired

    What the series is called.

  • status"active" | "paused" | "ended" | "suggested" | "dismissed"required

    Whether it is running: active, paused, ended, or suggested / dismissed for ones spotted from your transactions.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"required

    How often it repeats.

  • anchorDayintegerrequired

    Weekday (0 = Sunday) for weekly cadences, day of the month otherwise.

  • anchorMonthinteger | nullrequired

    Yearly series only.

  • intervalDaysinteger | nullrequired

    Custom cadence only: every N days.

Errors

  • conflict409

    Only an active series can be paused (reason: series_not_active).

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 200
{
  "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

POST/api/v1/recurring/{id}/resume
Needs bills:write

Makes a paused (or ended) series active again. Open occurrences from before the pause that are now in the past are skipped, never posted; send catchUpDueOns to bring back some of the missed days as pending occurrences. Resuming a series that is already active changes nothing.

Path parameters

  • idstringrequired

    The 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

  • idstringrequired

    The series id.

  • namestringrequired

    What the series is called.

  • status"active" | "paused" | "ended" | "suggested" | "dismissed"required

    Whether it is running: active, paused, ended, or suggested / dismissed for ones spotted from your transactions.

  • direction"expense" | "income" | "transfer"required

    Whether money goes out, comes in or moves between your own accounts.

  • cadence"weekly" | "fortnightly" | "four_weekly" | "monthly" | "quarterly" | "yearly" | "custom"required

    How often it repeats.

  • anchorDayintegerrequired

    Weekday (0 = Sunday) for weekly cadences, day of the month otherwise.

  • anchorMonthinteger | nullrequired

    Yearly series only.

  • intervalDaysinteger | nullrequired

    Custom cadence only: every N days.

Errors

  • conflict409

    Only a paused or ended series can be resumed (reason: series_not_paused).

  • validation_failed400

    A day in catchUpDueOns is not a YYYY-MM-DD day. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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 '{}'
Response 200
{
  "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

POST/api/v1/recurring/{id}/occurrences/{dueOn}/post
Needs bills:write

Posts the occurrence due on that day as a real transaction (the series’ category and payee are needed) and links it to the series. The answer is the occurrence, now posted, with the new transactionId. Send amountMinor or date to post a different amount or date than planned (the amount only on a plain, single-line occurrence). An occurrence not yet due (its due day is after today, UK time) cannot be posted, whatever date says: pre-approve it in the app or wait; one already posted or skipped cannot be posted either. On its due day it can be posted before its posting time, pending or pre-approved: without a date, the transaction is then dated the moment you post it, never later that day.

Path parameters

  • idstringrequired

    The recurring series id.

  • dueOnstringrequired

    The occurrence’s due day, YYYY-MM-DD, as dueOn in the series’ occurrences.

Request body (JSON)

  • datestring

    The transaction date to post it under (default: its due day). YYYY-MM-DD.

  • amountMinorinteger

    Post a different amount (in pence, positive) than planned.

Response fields

  • idstringrequired

    The occurrence id.

  • dueOnstringrequired

    The day it is due, YYYY-MM-DD.

  • status"pending" | "pre_approved" | "posted" | "skipped" | "cancelled"required

    Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled.

  • descriptionstringrequired

    What the transaction will be called.

  • transactionIdstring | nullrequired

    The ledger transaction it was posted as. Always null unless the key can read transactions.

  • postedAtstring | nullrequired

    When it was posted, ISO 8601 in UTC; null until then.

  • amountMinorintegerrequired

    Amount, in whole pence.

  • amountDisplaystringrequired

    Amount, ready to show, such as £12.50.

  • seriesIdstringrequired

    The series it belongs to.

Errors

  • validation_failed400

    The occurrence is not due yet (reason: not_due_yet), or is already posted or skipped. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • conflict409

    amountMinor is sent for an occurrence with several lines (reason: multiple_lines).

  • not_found404

    The series has no occurrence due on that day. Nothing exists with that id, or it belongs to someone else.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit).

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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

POST/api/v1/recurring/{id}/occurrences/{dueOn}/skip
Needs bills:write

Marks the occurrence due on that day as skipped: it will not be posted and stops showing as upcoming, and the series carries on. Nothing is posted to the ledger. Only a pending or pre-approved occurrence can be skipped.

Path parameters

  • idstringrequired

    The recurring series id.

  • dueOnstringrequired

    The occurrence’s due day, YYYY-MM-DD, as dueOn in the series’ occurrences.

Response fields

  • idstringrequired

    The occurrence id.

  • dueOnstringrequired

    The day it is due, YYYY-MM-DD.

  • status"pending" | "pre_approved" | "posted" | "skipped" | "cancelled"required

    Where it has got to: waiting, pre-approved, posted as a transaction, skipped or cancelled.

  • descriptionstringrequired

    What the transaction will be called.

  • transactionIdstring | nullrequired

    The ledger transaction it was posted as. Always null unless the key can read transactions.

  • postedAtstring | nullrequired

    When it was posted, ISO 8601 in UTC; null until then.

  • amountMinorintegerrequired

    Amount, in whole pence.

  • amountDisplaystringrequired

    Amount, ready to show, such as £12.50.

  • seriesIdstringrequired

    The series it belongs to.

Errors

  • validation_failed400

    Only a pending or pre-approved occurrence can be skipped.

  • not_found404

    The series has no occurrence due on that day. Nothing exists with that id, or it belongs to someone else.

  • forbidden403

    The key is limited to some accounts and this would involve another one (reason: account_limit).

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the bills:write scope; requiredScope names it.

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 200
{
  "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

GET/api/v1/budgets
Needs budgets:read

Every budget with its figures for one month, the same numbers as the Budgets page. planned is the month's allocation, funding envelope top-ups and transfers, spent what the ledger counted against the budget, and remaining what is left (negative when over; for rollover budgets it includes the opening balance carried in). progressPercent is spent as a share of everything available before it was spent, as on the Budgets page. status is over when nothing is left, near once the budget's own alert threshold has been reached, otherwise under. Archived budgets are hidden unless archived=include|only. The meta block says whether budgets are switched on for the account and gives the month's uncategorised spending and the cash reserved by active envelopes. To keep a copy in step, send updatedSince: only budgets edited since then come back, archived ones included and flagged. A budget counts as edited when the budget itself changes; its monthly figures move with your transactions without that, so re-read the months you show.

Query parameters

  • monthstring

    The month to show, YYYY-MM. Defaults to the current UK month.

  • archived"exclude" | "include" | "only"

    Archived items: exclude (default), include or only. With updatedSince the default is include, so a change to archived shows.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

Response fields

  • idstringrequired

    The budget id.

  • namestringrequired

    The budget name.

  • scope"category" | "account" | "envelope"required

    What it watches: a category, an account or an envelope of money set aside.

  • categoryobject | nullrequired

    The category (and its subcategories) this budget watches.

  • category.idstringrequired

    Its id.

  • category.namestringrequired

    Its name.

  • accountobject | nullrequired

    The financial account this budget is limited to.

  • account.idstringrequired

    Its id.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the budgets:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/budgets?month=2026-10' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/budgets/{id}
Needs budgets:read

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

  • idstringrequired

    The budget id.

Query parameters

  • monthstring

    The month to show, YYYY-MM. Defaults to the current UK month.

Response fields

  • idstringrequired

    The budget id.

  • namestringrequired

    The budget name.

  • scope"category" | "account" | "envelope"required

    What it watches: a category, an account or an envelope of money set aside.

  • categoryobject | nullrequired

    The category (and its subcategories) this budget watches.

  • category.idstringrequired

    Its id.

  • category.namestringrequired

    Its name.

  • accountobject | nullrequired

    The financial account this budget is limited to.

  • account.idstringrequired

    Its id.

Errors

  • not_found404

    The budget had not started by the requested month. Nothing exists with that id, or it belongs to someone else.

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the budgets:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/budgets/bud_groceries?month=2026-10' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

POST/api/v1/budgets
Needs budgets:write

Creates a budget, optionally with its first month's allocation (plannedMinor, in pence, for month). A category budget needs categoryId and an account budget needs accountId. Budgets must be switched on in the app first, otherwise the answer is 400. The answer is the budget as GET /budgets/{id} shows it for month.

Request body (JSON)

  • namestringrequired

    The budget name.

  • scope"category" | "account" | "envelope"required

    category watches one category and its subcategories, account one financial account, envelope is money you put aside and draw on.

  • categoryIdstring | null

    Required for a category budget.

  • accountIdstring | null

    The financial account, required for an account budget.

  • rolloverMode"none" | "carry" | "buffer"

    Defaults to none.

  • alertThresholdPercentinteger | null

    Percentage of the budget at which to warn you, 1–100. Null for no warning.

  • monthstring

    The month the first allocation is for, YYYY-MM. Defaults to the current UK month.

  • plannedMinorinteger

    The first month's allocation in pence. Leave out to set it later with PUT /budgets/{id}/months/{month}.

Response fields

  • idstringrequired

    The budget id.

  • namestringrequired

    The budget name.

  • scope"category" | "account" | "envelope"required

    What it watches: a category, an account or an envelope of money set aside.

  • categoryobject | nullrequired

    The category (and its subcategories) this budget watches.

  • category.idstringrequired

    Its id.

  • category.namestringrequired

    Its name.

  • accountobject | nullrequired

    The financial account this budget is limited to.

  • account.idstringrequired

    Its id.

Errors

  • validation_failed400

    Budgets are not switched on, a category budget has no categoryId, or an account budget has no accountId. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    The category or account does not exist or belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the budgets:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 201
{
  "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

PATCH/api/v1/budgets/{id}
Needs budgets:write

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

  • idstringrequired

    The budget id.

Request body (JSON)

  • namestring

    A new name.

  • categoryIdstring | null

    Watch a different category (category budgets).

  • accountIdstring | null

    Watch 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) or buffer (it builds a buffer).

  • alertThresholdPercentinteger | null

    Percentage of the budget at which to warn you, 1–100. Null for no warning.

  • archivedboolean

    True archives the budget. A budget cannot be restored once archived: false on an archived budget answers 409.

  • monthstring

    The month to show in the answer, YYYY-MM. Defaults to the current UK month.

  • versionstring

    The version you last read, as an alternative to the If-Match header.

Response fields

  • idstringrequired

    The budget id.

  • namestringrequired

    The budget name.

  • scope"category" | "account" | "envelope"required

    What it watches: a category, an account or an envelope of money set aside.

  • categoryobject | nullrequired

    The category (and its subcategories) this budget watches.

  • category.idstringrequired

    Its id.

  • category.namestringrequired

    Its name.

  • accountobject | nullrequired

    The financial account this budget is limited to.

  • account.idstringrequired

    Its id.

Errors

  • validation_failed400

    The body is empty, the scope is changed, or the rollover mode changes once the budget has buffer draws. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • conflict409

    The budget is archived, so it cannot be edited or restored (reason: budget_archived).

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the budgets:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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

PUT/api/v1/budgets/{id}/months/{month}
Needs budgets:write

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

  • idstringrequired

    The budget id.

  • monthstringrequired

    The month, YYYY-MM.

Request body (JSON)

  • amountMinorintegerrequired

    The month's allocation in pence.

  • versionstring

    The budget version you last read, as an alternative to the If-Match header.

Response fields

  • idstringrequired

    The budget id.

  • namestringrequired

    The budget name.

  • scope"category" | "account" | "envelope"required

    What it watches: a category, an account or an envelope of money set aside.

  • categoryobject | nullrequired

    The category (and its subcategories) this budget watches.

  • category.idstringrequired

    Its id.

  • category.namestringrequired

    Its name.

  • accountobject | nullrequired

    The financial account this budget is limited to.

  • account.idstringrequired

    Its id.

Errors

  • conflict409

    The budget is archived (reason: budget_archived).

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • validation_failed400

    A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the budgets:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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

GET/api/v1/goals
Needs goals:read

Savings and payoff goals with their progress. progress is what the Goals page shows: for a savings goal the cash set aside for it that the account still covers, for a payoff goal the debt repaid since it began; never above the target. shortfall is what is still missing, reserved is the cash earmarked for the goal, and requiredPerMonth is the even monthly amount needed to meet the deadline (null without one). Archived goals are hidden unless archived=include|only. The meta block totals the cash reserved across active goals and how much of it the accounts still cover. To keep a copy in step, send updatedSince: only goals edited since then come back, archived ones included and flagged. A goal counts as edited when the goal itself changes; its progress moves with your transactions and funding without that, so refresh the figures you show.

Query parameters

  • archived"exclude" | "include" | "only"

    Archived items: exclude (default), include or only. With updatedSince the default is include, so a change to archived shows.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check).

Response fields

  • idstringrequired

    The goal id.

  • namestringrequired

    The goal name.

  • type"savings" | "payoff"required

    savings builds towards a target; payoff clears a debt.

  • progressPercentintegerrequired

    Progress as a whole percentage of the target.

  • deadlinestring | nullrequired

    Calendar day, YYYY-MM-DD.

  • deadlineStatus"none" | "future" | "due" | "overdue" | "met"required

    How the deadline stands: none when there is no deadline, future, due today, overdue, or met once the target is reached.

  • remainingDaysinteger | nullrequired

    Days to the deadline; negative once it has passed.

  • accountobjectrequired

    The account the goal is measured on.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the goals:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/goals \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/goals/{id}
Needs goals:read

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

  • idstringrequired

    The goal id.

Response fields

  • idstringrequired

    The goal id.

  • namestringrequired

    The goal name.

  • type"savings" | "payoff"required

    savings builds towards a target; payoff clears a debt.

  • progressPercentintegerrequired

    Progress as a whole percentage of the target.

  • deadlinestring | nullrequired

    Calendar day, YYYY-MM-DD.

  • deadlineStatus"none" | "future" | "due" | "overdue" | "met"required

    How the deadline stands: none when there is no deadline, future, due today, overdue, or met once the target is reached.

  • remainingDaysinteger | nullrequired

    Days to the deadline; negative once it has passed.

  • accountobjectrequired

    The account the goal is measured on.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the goals:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/goals/goal_holiday \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

POST/api/v1/goals
Needs goals:write

Creates a savings or payoff goal. A savings goal is measured on a cash or savings account; a payoff goal on a credit account that currently owes money, and may name a cash account to fund it. The answer is the goal as GET /goals/{id} shows it.

Request body (JSON)

  • namestringrequired

    The goal name.

  • type"savings" | "payoff"required

    savings sets cash aside in a cash or savings account; payoff repays the debt on a credit account.

  • targetMinorintegerrequired

    The target in pence. For a payoff goal it cannot exceed the debt now.

  • deadlinestring | null

    The day to reach the target by, YYYY-MM-DD. Null for no deadline.

  • accountIdstringrequired

    The account the goal is measured on: where savings are held, or the credit account to pay off.

  • fundingAccountIdstring | null

    For a payoff goal, the cash account its reserved money comes from.

Response fields

  • idstringrequired

    The goal id.

  • namestringrequired

    The goal name.

  • type"savings" | "payoff"required

    savings builds towards a target; payoff clears a debt.

  • progressPercentintegerrequired

    Progress as a whole percentage of the target.

  • deadlinestring | nullrequired

    Calendar day, YYYY-MM-DD.

  • deadlineStatus"none" | "future" | "due" | "overdue" | "met"required

    How the deadline stands: none when there is no deadline, future, due today, overdue, or met once the target is reached.

  • remainingDaysinteger | nullrequired

    Days to the deadline; negative once it has passed.

  • accountobjectrequired

    The account the goal is measured on.

Errors

  • validation_failed400

    A savings goal is on a credit account, or a payoff goal is on an account that owes nothing. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    The account or funding account does not exist or belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the goals:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 201
{
  "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

PATCH/api/v1/goals/{id}
Needs goals:write

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

  • idstringrequired

    The goal id.

Request body (JSON)

  • namestring

    A new name.

  • type"savings" | "payoff"

    Changing the type needs the goal to have no reserved funds.

  • targetMinorinteger

    A new target in pence; it cannot be below what is reserved.

  • deadlinestring | null

    The day to reach the target by, YYYY-MM-DD. Null for no deadline.

  • accountIdstring

    Measure on a different account; needs no reserved funds.

  • fundingAccountIdstring | null

    A payoff goal's funding account.

  • archivedboolean

    True archives the goal; false restores it (the account must cover its reserve).

  • versionstring

    The version you last read, as an alternative to the If-Match header.

Response fields

  • idstringrequired

    The goal id.

  • namestringrequired

    The goal name.

  • type"savings" | "payoff"required

    savings builds towards a target; payoff clears a debt.

  • progressPercentintegerrequired

    Progress as a whole percentage of the target.

  • deadlinestring | nullrequired

    Calendar day, YYYY-MM-DD.

  • deadlineStatus"none" | "future" | "due" | "overdue" | "met"required

    How the deadline stands: none when there is no deadline, future, due today, overdue, or met once the target is reached.

  • remainingDaysinteger | nullrequired

    Days to the deadline; negative once it has passed.

  • accountobjectrequired

    The account the goal is measured on.

Errors

  • validation_failed400

    The body is empty, the type or account changes while funds are reserved, or the target drops below what is reserved. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    The account or funding account does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the goals:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 200
{
  "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

POST/api/v1/goals/{id}/funding
Needs goals:write

Adds a funding entry: a positive amountMinor (pence) sets cash aside for the goal, a negative one releases it. Nothing moves between accounts; the money stays where it is and is reserved on paper. It needs enough unreserved cash in the funding account, cannot take the reserve above the target or below zero, and date cannot be in the future. Archived goals cannot be funded. The answer is the new entry, with the goal as it now stands.

Path parameters

  • idstringrequired

    The goal id.

Request body (JSON)

  • amountMinorintegerrequired

    Pence to reserve (positive) or release (negative).

  • datestringrequired

    The day the money was set aside, YYYY-MM-DD, today or earlier.

  • notestring | null

    A short note shown in the goal's history.

Response fields

  • idstringrequired

    The funding entry id.

  • occurredOnstringrequired

    The day the money was put towards the goal, YYYY-MM-DD.

  • notestring | nullrequired

    A short note.

  • createdAtstring | nullrequired

    When it was created, ISO 8601 in UTC.

  • amountMinorintegerrequired

    The amount put towards the goal, in whole pence.

  • amountDisplaystringrequired

    The amount put towards the goal, ready to show, such as £12.50.

  • goalobjectrequired

    The goal after the change.

  • goal.idstringrequired

    The goal id.

Errors

  • validation_failed400

    The funding account lacks enough unreserved cash, the reserve would pass the target or drop below zero, the goal is archived, or date is in the future. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the goals:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 201
{
  "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

POST/api/v1/connection/payslips
Needs documents:upload

Uploads a payslip (a multipart/form-data form with the file in file, at most 4 MB) and attaches it to transactionId, a payment the app can see. It is filed as a payslip, so JAG Finance reads it and Itemise salary can run. Answers 201 with the document; when the same file is already a document, that one is attached instead (200).

Query parameters

  • transactionIdstringrequired

    The payment (income) to attach the payslip to.

Response fields

  • status"added" | "existing"required

    added for a new document; existing when the same file was already one.

  • documentIdstringrequired

    The payslip.

  • transactionIdstringrequired

    The payment it is attached to.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the documents:upload scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 201
{
  "data": {
    "status": "added",
    "documentId": "doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91",
    "transactionId": "txn_1"
  }
}

List documents

GET/api/v1/documents
Needs documents:read

Your documents, newest first (by the date each is filed under). Pass tab=trash to see the Trash. linkCount counts only the attachments to areas the key can read (transactions, inbox items, accounts); the linked filter and the unfiled tab look at all attachments. To keep a copy in step, send updatedSince: only documents changed since then come back, trashed ones included and flagged. Answers 404 while documents are switched off for the whole app. A connected app gets only the payslips it may read, by pay date for from and to, and linkCount counts only what it can see; its pages can come back short, so follow page.nextCursor until it is null.

Query parameters

  • tab"all" | "unfiled" | "review" | "trash"

    all (default), unfiled (attached to nothing), review (waiting in the Documents inbox) or trash. With updatedSince and no tab, the Trash is included.

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check). A document counts as changed on an edit, a link, or a step in its reading. A trashed document comes back with trashedAt set; once the Trash is emptied it is gone for good.

  • kindstring | string[]

    Only these kinds, comma-separated: receipt,invoice. unknown is a document with no kind set.

  • sourcestring | string[]

    Only documents that arrived this way: upload, shortcut, share_target, email or system.

  • linked"0" | "1" | "true" | "false"

    true for documents attached to anything (a transaction, an inbox item or an account, whatever the key can read), false for those attached to nothing.

  • fromstring

    First day (YYYY-MM-DD) of the date a document is filed under, inclusive.

  • tostring

    Last day (YYYY-MM-DD) of the date a document is filed under, inclusive.

  • qstring

    Words to find in titles, file names, notes and the text read from the pages. Every word must match.

  • limitinteger

    Documents per page, 1 to 100. Default 50.

  • cursorstring

    page.nextCursor from the previous page.

Response fields

  • idstringrequired

    Starts with doc_.

  • titlestringrequired

    Its title, else the file’s name, else Photo or PDF.

  • titleSource"user" | "transaction" | nullrequired

    What named it, when it was not the file.

  • kindstringrequired

    receipt, invoice, statement, payslip, tax, policy, warranty, letter, summary, other or unknown.

  • source"upload" | "shortcut" | "share_target" | "email" | "system"required

    How it arrived.

  • mimeTypestringrequired

    The file type of the first file, such as application/pdf.

  • family"image" | "pdf"required

    Whether it is made of images or is a PDF.

  • partCountintegerrequired

    Files that make it up: photos of a long receipt, say.

Errors

  • not_found404

    Documents are switched off for the whole app.

  • unavailable503

    The document vault is not answering.

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the documents:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/documents?tab=unfiled&kind=receipt&limit=20' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/documents/search
Needs documents:read

Finds documents about what you describe, even when the words differ ("car insurance renewal" finds the policy letter). Closest first, and only documents within a sensible distance. Your words are sent to the DocIntel service to be turned into a vector; they are never kept. Answers 503 unavailable while search by meaning is switched off or DocIntel is down or waking (see Retry-After); use GET /documents?q= for a plain word search.

Query parameters

  • qstringrequired

    What 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.

  • limitinteger

    Documents to return, 1 to 20. Default 10.

Response fields

  • idstringrequired

    Starts with doc_.

  • titlestringrequired

    Its title, else the file’s name, else Photo or PDF.

  • titleSource"user" | "transaction" | nullrequired

    What named it, when it was not the file.

  • kindstringrequired

    receipt, invoice, statement, payslip, tax, policy, warranty, letter, summary, other or unknown.

  • source"upload" | "shortcut" | "share_target" | "email" | "system"required

    How it arrived.

  • mimeTypestringrequired

    The file type of the first file, such as application/pdf.

  • family"image" | "pdf"required

    Whether it is made of images or is a PDF.

  • partCountintegerrequired

    Files that make it up: photos of a long receipt, say.

Errors

  • unavailable503

    Search by meaning is switched off, or DocIntel is down or waking; retry after Retry-After, or use GET /documents?q=.

  • not_found404

    Documents are switched off for the whole app.

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the documents:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/documents/search?q=pharmacy+receipt+for+vitamins' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/documents/{id}
Needs documents:read

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

  • idstringrequired

    The document, starts with doc_.

Response fields

  • idstringrequired

    Starts with doc_.

  • titlestringrequired

    Its title, else the file’s name, else Photo or PDF.

  • titleSource"user" | "transaction" | nullrequired

    What named it, when it was not the file.

  • kindstringrequired

    receipt, invoice, statement, payslip, tax, policy, warranty, letter, summary, other or unknown.

  • source"upload" | "shortcut" | "share_target" | "email" | "system"required

    How it arrived.

  • mimeTypestringrequired

    The file type of the first file, such as application/pdf.

  • family"image" | "pdf"required

    Whether it is made of images or is a PDF.

  • partCountintegerrequired

    Files that make it up: photos of a long receipt, say.

Errors

  • not_found404

    Documents are switched off for the whole app, or the document does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • unavailable503

    The document vault is not answering.

  • forbidden_scope403

    The key lacks the documents:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/documents/doc_3b8e5d2a-7c41-4f6a-9e0d-2a1b4c6d8e0f \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/documents/{id}/text
Needs documents:read

The text read from each page: a PDF’s own text, the app’s reading of a photo, or Live Text from the phone. Account and card numbers are already masked to their last four. Very long documents stop at 50,000 characters (truncated). pages is empty for a document with no text yet.

Path parameters

  • idstringrequired

    The document, starts with doc_.

Response fields

  • idstringrequired

    The document id.

  • sourcestring | nullrequired

    Where most of the text came from: the PDF’s own text, the app’s reading of the photo, or Live Text.

  • charactersintegerrequired

    Length of all the text, even when pages stops short.

  • pagesWithTextintegerrequired

    How many pages have any text.

  • truncatedbooleanrequired

    True when long documents were cut to the first 50,000 characters.

  • textstringrequired

    The pages joined with a blank line between them.

  • pagesobject[]required

    The text page by page; stops short of characters when the text was cut.

  • pages[].pageintegerrequired

    The page number, from 1.

  • pages[].sourcestringrequired

    Where the text of this page came from.

  • pages[].textstringrequired

    The text of the page.

Errors

  • not_found404

    Documents are switched off for the whole app, or the document does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • unavailable503

    The document vault is not answering.

  • forbidden_scope403

    The key lacks the documents:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/text \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/documents/{id}/file
Needs documents:read

Answers 302 to a link that works for about a minute, so send the request with -L (curl) and without the key on the second hop. Add as=link to get { url, expiresAt } instead and fetch it yourself. The link is never cached or logged. Answers 503 unavailable (with Retry-After) while document storage is down; a file the storage no longer holds is a 404.

Path parameters

  • idstringrequired

    The document, starts with doc_.

Query parameters

  • partinteger

    Which file of a document with several photos, from 1. For variant=page it 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), thumb or unlocked (a password-protected PDF, unlocked).

  • download"0" | "1" | "true" | "false"

    true to have the file saved rather than shown in a browser.

  • as"link"

    link answers with { url, expiresAt } instead of redirecting.

Response fields

  • urlstringrequired

    A short-lived address to download the file from.

  • expiresAtstringrequired

    When the address stops working, ISO 8601 in UTC.

Errors

  • not_found404

    Documents are switched off for the whole app, the document or the part you asked for does not exist, or storage no longer holds the file. Nothing exists with that id, or it belongs to someone else.

  • unavailable503

    Document storage is down or not set up; retry after the Retry-After seconds.

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the documents:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/documents/doc_6f1c0d0e-2b4a-4f0e-9a52-0d1f3c5b7a91/file?as=link' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "data": {
    "url": "https://files.example.com/…signed…",
    "expiresAt": "2026-10-26T09:01:00.000Z"
  }
}

Upload a document in one request

POST/api/v1/documents
Needs documents:upload

Adds a photo or PDF to your Documents inbox. Send a multipart/form-data form with the file in a field named file (several photos become the pages of one document) and, optionally, text read on the phone (Live Text) in clientOcrText. All files together can be at most 4 MB: for anything bigger, or a long receipt, use POST /documents/uploads. Answers 201 added with the new document’s id and the address that opens it in the app, or 200 duplicate when the same file is already a document (which document has it is never said). Counts against the key’s 200 upload calls per UK day (rate_limited, reason: daily_limit). A key with documents:upload or documents:write can use it. Send an Idempotency-Key to make a retry safe: the same key with the same file answers the first result again, the same key with another file is a 422.

Response fields

  • status"added" | "duplicate"required

    added for a new document, duplicate when the file was already there.

  • documentIdstring

    The new document. Not given for a duplicate.

  • urlstring

    Where the document opens in the app. Not given for a duplicate.

Errors

  • validation_failed400

    The request is not a multipart/form-data form (reason: not_multipart) or has no file (reason: no_file).

  • payload_too_large413

    The files together are over 4 MB (reason: too_large); use POST /documents/uploads.

  • rate_limited429

    The key has used its 200 upload calls for the UK day (reason: daily_limit). The key has used up its rate limit; wait Retry-After seconds.

  • unavailable503

    Document storage is down or not set up; retry after the Retry-After seconds.

  • not_found404

    Documents are switched off for the whole app.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the documents:upload scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

Request
curl -X POST https://finance.jagwebsites.xyz/api/v1/documents \
  -H 'Authorization: Bearer sk_your_key' \
  -H 'Idempotency-Key: 8d6f6c1e-3b0a-4a52-9a43-2f1e5c0d7a11'
Response 201
{
  "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

POST/api/v1/documents/uploads
Needs documents:upload

Step 1 of an upload that does not fit in one request: declare the file (its type, size and SHA-256), then send its bytes to the upload form this returns, add any further pages with POST /documents/{id}/parts, and finish with POST /documents/{id}/complete. Declaring the same file again while it is unfinished gives the same upload back. A key always gets an upload; whether the file is already a document is only decided from its bytes at complete. Counts against the key’s 200 upload calls per UK day.

Request body (JSON)

  • namestring | null

    The file’s name, such as IMG_2041.jpg.

  • typestringrequired

    The MIME type: image/jpeg, image/png, image/heic or application/pdf.

  • sizeintegerrequired

    The file’s size in bytes.

  • sha256stringrequired

    The SHA-256 of the file’s bytes, in hex (64 characters).

  • clientOcrTextstring | null

    Text read on the phone (Live Text). It only helps find the transaction.

Response fields

  • status"upload" | "duplicate"required

    upload when the file should be sent to upload; duplicate when it is already a document.

  • documentIdstring

    The document being uploaded.

  • partinteger

    Always 1 here.

  • uploadobject

    Send the file to this form (a POST of fields plus the file in file, or a PUT with headers) before it expires.

  • upload.method"POST" | "PUT"required

    The HTTP method to send the file with.

  • upload.urlstringrequired

    The address to send the file to.

  • upload.fieldsobject

    POST only: form fields to send before the file.

  • upload.headersobject

    PUT only: headers to send with the file.

  • upload.expiresAtstringrequired

    When the form stops working, ISO 8601 in UTC.

Errors

  • rate_limited429

    The key has used its 200 upload calls for the UK day (reason: daily_limit). The key has used up its rate limit; wait Retry-After seconds.

  • unavailable503

    Document storage is down or not set up; retry after the Retry-After seconds.

  • not_found404

    Documents are switched off for the whole app.

  • validation_failed400

    A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the documents:upload scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

Request
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"
  }'
Response 201
{
  "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

POST/api/v1/documents/{id}/parts
Needs documents:upload

Another page for a photo document that is still uploading, up to 20 (a long receipt). Declare it like the first file, with part set to its page number (2 for the second); a retry sends the same number. Then send its bytes to the upload form this returns.

Path parameters

  • idstringrequired

    The document, starts with doc_.

Request body (JSON)

  • namestring | null

    The file’s name, such as IMG_2041.jpg.

  • typestringrequired

    The MIME type: image/jpeg, image/png, image/heic or application/pdf.

  • sizeintegerrequired

    The file’s size in bytes.

  • sha256stringrequired

    The SHA-256 of the file’s bytes, in hex (64 characters).

  • clientOcrTextstring | null

    Text read on the phone (Live Text). It only helps find the transaction.

  • partintegerrequired

    The page this file is: 2 for the second, and so on. A retry sends the same number.

Response fields

  • documentIdstringrequired

    The document this page belongs to.

  • partintegerrequired

    The page number this upload is for.

  • uploadobjectrequired

    Where to send the file’s bytes.

  • upload.method"POST" | "PUT"required

    The HTTP method to send the file with.

  • upload.urlstringrequired

    The address to send the file to.

  • upload.fieldsobject

    POST only: form fields to send before the file.

  • upload.headersobject

    PUT only: headers to send with the file.

  • upload.expiresAtstringrequired

    When the form stops working, ISO 8601 in UTC.

Errors

  • not_found404

    The upload does not exist, is not yours, or has already been finished. Nothing exists with that id, or it belongs to someone else.

  • rate_limited429

    The key has used its 200 upload calls for the UK day (reason: daily_limit). The key has used up its rate limit; wait Retry-After seconds.

  • unavailable503

    Document storage is down or not set up; retry after the Retry-After seconds.

  • validation_failed400

    A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the documents:upload scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

Request
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
  }'
Response 201
{
  "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

POST/api/v1/documents/{id}/complete
Needs documents:upload

The last step of an upload: checks that every page arrived, then the document counts and lands in the Documents inbox. Safe to repeat. Answers 409 with reason: not_uploaded while a page is still on its way. The same file already in Documents is only found here, from its bytes: duplicate, without saying which document has it, and the upload is dropped.

Path parameters

  • idstringrequired

    The document, starts with doc_.

Response fields

  • status"added" | "duplicate"required

    added for a new document, duplicate when the file was already there.

  • documentIdstring

    Not given for a duplicate.

  • urlstring

    Where the document opens in the app. Not given for a duplicate.

Errors

  • conflict409

    A page has not arrived yet (reason: not_uploaded); send it, then try again.

  • not_found404

    Documents are switched off for the whole app, or the upload does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • unavailable503

    Document storage is down or not set up; retry after the Retry-After seconds.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the documents:upload scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 200
{
  "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

PATCH/api/v1/documents/{id}
Needs documents:write

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

  • idstringrequired

    The document, starts with doc_.

Request body (JSON)

  • titlestring | null

    A new title, up to 200 characters. null or 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, other or unknown (not set).

  • notesstring | null

    Your notes, up to 5000 characters. null or blank clears them.

  • datestring | null

    The day it is dated, YYYY-MM-DD, from 2000 to tomorrow. null clears it (and its time), so it is filed under when it was taken or arrived again.

  • timestring | null

    The time of that day it is dated, HH:MM on the UK clock (Europe/London); it needs a date, sent with it or already set. null clears it. Left out, it stays, unless date changes to another day.

  • paidDatestring | null

    The day it was paid, YYYY-MM-DD, for a document on no transaction (one on a transaction is paid that transaction’s day). null clears it.

  • reviewedboolean

    true files a document waiting in the Documents inbox without a transaction; false sends it to the Documents inbox, from anywhere in the vault. What it is attached to stays.

  • versionstring

    The version you last read; the same as sending If-Match.

Response fields

  • idstringrequired

    Starts with doc_.

  • titlestringrequired

    Its title, else the file’s name, else Photo or PDF.

  • titleSource"user" | "transaction" | nullrequired

    What named it, when it was not the file.

  • kindstringrequired

    receipt, invoice, statement, payslip, tax, policy, warranty, letter, summary, other or unknown.

  • source"upload" | "shortcut" | "share_target" | "email" | "system"required

    How it arrived.

  • mimeTypestringrequired

    The file type of the first file, such as application/pdf.

  • family"image" | "pdf"required

    Whether it is made of images or is a PDF.

  • partCountintegerrequired

    Files that make it up: photos of a long receipt, say.

Errors

  • validation_failed400

    The body is empty, or kind is not one of the document kinds. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • not_found404

    Documents are switched off for the whole app, or the document does not exist or belongs to someone else or is in the Trash and must be restored first. Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the documents:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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
  }'
Response 200
{
  "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"
        }
      }
    ]
  }
}

Detach a document

DELETE/api/v1/documents/{id}/links/{linkId}
Needs documents:write

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

  • idstringrequired

    The document, starts with doc_.

  • linkIdstringrequired

    The attachment, starts with dln_.

Errors

  • not_found404

    The document or the link does not exist or belongs to someone else. Nothing exists with that id, or it belongs to someone else.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the documents:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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

DELETE/api/v1/documents/{id}
Needs documents:delete

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

  • idstringrequired

    The document, starts with doc_.

Errors

  • not_found404

    Documents are switched off for the whole app, or the document does not exist or belongs to someone else or is already in the Trash. Nothing exists with that id, or it belongs to someone else.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the documents:delete scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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

POST/api/v1/documents/{id}/restore
Needs documents:write

Brings a document back from the Trash while it is still there (purgeAfter has not passed), with its attachments. If the same file was added again meanwhile, that copy wins: the answer is a 409 conflict with reason: duplicate, naming the live document as duplicateDocumentId when the key can read documents. Answers with the document as GET /documents/{id} shows it.

Path parameters

  • idstringrequired

    The document, starts with doc_.

Response fields

  • idstringrequired

    Starts with doc_.

  • titlestringrequired

    Its title, else the file’s name, else Photo or PDF.

  • titleSource"user" | "transaction" | nullrequired

    What named it, when it was not the file.

  • kindstringrequired

    receipt, invoice, statement, payslip, tax, policy, warranty, letter, summary, other or unknown.

  • source"upload" | "shortcut" | "share_target" | "email" | "system"required

    How it arrived.

  • mimeTypestringrequired

    The file type of the first file, such as application/pdf.

  • family"image" | "pdf"required

    Whether it is made of images or is a PDF.

  • partCountintegerrequired

    Files that make it up: photos of a long receipt, say.

Errors

  • conflict409

    The same file was added again while this one was in the Trash (reason: duplicate).

  • not_found404

    Documents are switched off for the whole app, or the document does not exist or belongs to someone else, is not in the Trash, or has been removed for good. Nothing exists with that id, or it belongs to someone else.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the documents:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 200
{
  "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

GET/api/v1/inbox
Needs inbox:read

Wallet purchases waiting for review, oldest first, as the inbox works through them. Amounts are negative (money spent); hasAmount is false for a purchase that arrived without one. The suggested payee, category and account are what the app would pre-fill; they are only suggestions, nothing is approved by reading them. To keep a copy in step, send updatedSince: items that changed since then come back whatever their status, so one you approved or dismissed shows with that status. A dismissed item that is later deleted in the app no longer appears.

Query parameters

  • updatedSincestring

    Only items changed at or after this time (inclusive): an ISO 8601 timestamp such as 2026-10-24T18:30:00Z (no offset means UK time; a plain date is the start of that UK day). Send the page.asOf of your last run (of its first page, if it took several), not the newest updatedAt you saw; it is a few seconds before the read, so an item may come back twice: update by id. Items that were archived or trashed since then come back with that state. Deleted items are not listed (compare ids for a full check). Lists items of every status that changed (approved, dismissed and expired ones too, flagged by status), oldest first, and without suggestions for those no longer pending.

  • limitinteger

    Items per page, 1 to 50. Default 50.

  • cursorstring

    page.nextCursor from the previous page.

Response fields

  • idstringrequired

    The inbox item id.

  • status"pending" | "approved" | "dismissed" | "expired"required

    pending waits for you; approved became a transaction; dismissed was thrown away; expired was left too long.

  • merchantstringrequired

    The merchant as the wallet sent it.

  • amountMinorintegerrequired

    Whole pence, negative for money spent. 0 when the purchase arrived without an amount.

  • amountDisplaystringrequired

    The amount ready to show, such as -£4.80.

  • hasAmountbooleanrequired

    False when the purchase arrived without an amount and waits for you to fill it in.

  • originalobject | nullrequired

    What was charged in the merchant’s own currency, for a foreign purchase.

  • original.currencystringrequired

    The three-letter currency code charged, such as EUR.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the inbox:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/inbox?limit=20' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/inbox/{id}
Needs inbox:read

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

  • idstringrequired

    The inbox item.

Response fields

  • idstringrequired

    The inbox item id.

  • status"pending" | "approved" | "dismissed" | "expired"required

    pending waits for you; approved became a transaction; dismissed was thrown away; expired was left too long.

  • merchantstringrequired

    The merchant as the wallet sent it.

  • amountMinorintegerrequired

    Whole pence, negative for money spent. 0 when the purchase arrived without an amount.

  • amountDisplaystringrequired

    The amount ready to show, such as -£4.80.

  • hasAmountbooleanrequired

    False when the purchase arrived without an amount and waits for you to fill it in.

  • originalobject | nullrequired

    What was charged in the merchant’s own currency, for a foreign purchase.

  • original.currencystringrequired

    The three-letter currency code charged, such as EUR.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the inbox:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/inbox/wallet_import_id \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

POST/api/v1/inbox
Needs wallet:write

Queues a wallet purchase for review, like POST /api/import/wallet but with money in whole pence. Nothing is posted to the ledger yet unless one of your auto-approve rules trusts it, in which case autoApproved is true and the item is already approved. A key with wallet:write or inbox:write can use it. Send an Idempotency-Key header (or idempotencyKey in the body) so a retry never queues the purchase twice: the same key answers the item already queued, with deduplicated: true and a 200. The key is shared with POST /api/import/wallet, across API keys: a purchase queued there under the same key is answered here as a repeat, and the other way round. Suggested payee, category and account are included only when the key can also read the inbox and the area each suggestion comes from.

Request body (JSON)

  • merchantstring | null

    The merchant or title shown in the inbox. Leave it out when the wallet cannot say.

  • amountMinorinteger | null

    Pence spent, as a positive whole number (495 is £4.95). Leave it out, or send 0, for a purchase that arrived without an amount: it waits for you to fill it in.

  • transactionDatestring

    The day of the purchase: YYYY-MM-DD or an ISO 8601 date-time (no offset means UK time). Wins over date. Dates like 05/10/2026 are refused: the day and month order would be a guess.

  • datestring

    The same as transactionDate, for clients that call it this.

  • cardstring

    The card label the wallet sent, such as Visa •• 4242. It helps pick the account.

  • namestring

    The name of the Shortcut sending this.

  • idempotencyKeystring

    Makes a retry safe, like the Idempotency-Key header (send either; if both, they must match). A purchase already queued under this key is answered again, not queued twice.

  • metadataobject

    Anything else worth keeping with the purchase. Kept as sent and shown in its history.

  • originalCurrencystring | null
  • originalAmountMinorinteger | null
  • fxRatenumber | string | null
  • fxSource"manual" | "derived" | "frankfurter" | null
  • fxAsOfstring | null

Response fields

  • idstringrequired

    The inbox item id.

  • status"pending" | "approved" | "dismissed" | "expired"required

    pending waits for you; approved became a transaction; dismissed was thrown away; expired was left too long.

  • merchantstringrequired

    The merchant as the wallet sent it.

  • amountMinorintegerrequired

    Whole pence, negative for money spent. 0 when the purchase arrived without an amount.

  • amountDisplaystringrequired

    The amount ready to show, such as -£4.80.

  • hasAmountbooleanrequired

    False when the purchase arrived without an amount and waits for you to fill it in.

  • originalobject | nullrequired

    What was charged in the merchant’s own currency, for a foreign purchase.

  • original.currencystringrequired

    The three-letter currency code charged, such as EUR.

Errors

  • validation_failed400

    The Idempotency-Key header and the idempotencyKey in the body differ, or the foreign-currency amounts do not add up. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the wallet:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 201
{
  "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

POST/api/v1/inbox/{id}/approve
Needs inbox:write

Posts a pending purchase to the ledger as an expense. Send only what you want to override: anything left out is filled from what the app has saved for this merchant (its payee, category and account), or the one card the label names. If the pocket, category or payee still cannot be told, nothing is posted and the answer is a 400 naming the fields to send. The choices are saved as the merchant’s mapping, as approving in the app does. The answer is the item, now approved, with the transactionId it became; amountMinor is what was posted. Answers 404 for an unknown item and 409 not_pending for one already approved, dismissed or expired. A purchase in a foreign currency with no exchange rate yet must be approved in the app.

Path parameters

  • idstringrequired

    The inbox item.

Request body (JSON)

  • categoryIdstring

    The category to post under. Left out, the one saved for this merchant is used.

  • payeeIdstring

    The payee. Left out, the one saved for this merchant is used.

  • accountIdstring

    The card or pot it was paid from, or a financial account id to use its Direct source. Left out, the saved one, or the one card the label names, is used.

  • descriptionstring

    The transaction’s description. Left out, the merchant as the wallet sent it.

  • amountMinorinteger

    Pence to post, as a positive whole number. Needed when the purchase arrived without an amount; also corrects one.

Response fields

  • idstringrequired

    The inbox item id.

  • status"pending" | "approved" | "dismissed" | "expired"required

    pending waits for you; approved became a transaction; dismissed was thrown away; expired was left too long.

  • merchantstringrequired

    The merchant as the wallet sent it.

  • amountMinorintegerrequired

    Whole pence, negative for money spent. 0 when the purchase arrived without an amount.

  • amountDisplaystringrequired

    The amount ready to show, such as -£4.80.

  • hasAmountbooleanrequired

    False when the purchase arrived without an amount and waits for you to fill it in.

  • originalobject | nullrequired

    What was charged in the merchant’s own currency, for a foreign purchase.

  • original.currencystringrequired

    The three-letter currency code charged, such as EUR.

Errors

  • validation_failed400

    The account, category or payee cannot be worked out (reason: missing_fields; details names what to send), or the purchase has no amount. A body field is missing, wrong, or not one this endpoint knows; details lists each.

  • conflict409

    The item is not pending: it was already approved, dismissed or has expired (reason: not_pending).

  • not_found404

    The item does not exist or belongs to someone else, or an account, category or payee you sent does not. Nothing exists with that id, or it belongs to someone else.

  • invalid_json400

    The body is not valid JSON.

  • unsupported_media_type415

    The body is not JSON; send Content-Type: application/json.

  • payload_too_large413

    The body is over the 1 MB limit.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the inbox:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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"
  }'
Response 200
{
  "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

POST/api/v1/inbox/{id}/dismiss
Needs inbox:write

Sets a pending purchase aside without posting anything. It stays in the app’s dismissed list, where it can be restored, until it is deleted with DELETE /inbox/{id}. Answers 404 once the item is no longer pending.

Path parameters

  • idstringrequired

    The inbox item.

Response fields

  • idstringrequired

    The inbox item id.

  • status"pending" | "approved" | "dismissed" | "expired"required

    pending waits for you; approved became a transaction; dismissed was thrown away; expired was left too long.

  • merchantstringrequired

    The merchant as the wallet sent it.

  • amountMinorintegerrequired

    Whole pence, negative for money spent. 0 when the purchase arrived without an amount.

  • amountDisplaystringrequired

    The amount ready to show, such as -£4.80.

  • hasAmountbooleanrequired

    False when the purchase arrived without an amount and waits for you to fill it in.

  • originalobject | nullrequired

    What was charged in the merchant’s own currency, for a foreign purchase.

  • original.currencystringrequired

    The three-letter currency code charged, such as EUR.

Errors

  • not_found404

    The item does not exist or belongs to someone else, or is no longer pending. Nothing exists with that id, or it belongs to someone else.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the inbox:write scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 200
{
  "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

DELETE/api/v1/inbox/{id}
Needs inbox:delete

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

  • idstringrequired

    The inbox item.

Errors

  • not_found404

    The item does not exist or belongs to someone else, or has not been dismissed. Nothing exists with that id, or it belongs to someone else.

  • version_conflict412

    The If-Match version (or version in the body) is out of date; read the item again and retry.

  • idempotency_in_progress409

    A call with the same Idempotency-Key is still running; wait, then retry.

  • idempotency_outcome_unknown409

    The first call with this Idempotency-Key may have completed but its answer was lost; check the data before retrying.

  • idempotency_conflict422

    The Idempotency-Key was already used with a different request.

  • forbidden_scope403

    The key lacks the inbox:delete scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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

GET/api/v1/insights/totals
Needs totals:read

Income, spending and net between two dates, optionally split by day, week (Monday to Sunday) or month. Transfers between your own accounts are left out; refunds and other adjustments reduce the side they belong to. Days are UK calendar days. Every group in the range is listed, empty ones as zero, and the first and last are cut to the range. meta.total is worked out over the whole range. Also open to keys that only have the narrow totals:read scope.

Query parameters

  • fromstring

    Start of the range: YYYY-MM-DD (that whole UK day) or an ISO 8601 timestamp. Default: 29 days before to.

  • tostring

    End 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, month or none (one group, the default).

Response fields

  • startstringrequired

    First UK day of the group inside the range.

  • endstringrequired

    Last UK day of the group inside the range.

  • lineCountintegerrequired

    Ledger lines counted.

  • incomeMinorintegerrequired

    Income, in whole pence.

  • incomeDisplaystringrequired

    Income, ready to show, such as £12.50.

  • spendingMinorintegerrequired

    Spending, in whole pence.

  • spendingDisplaystringrequired

    Spending, ready to show, such as £12.50.

  • netMinorintegerrequired

    Net, in whole pence.

  • netDisplaystringrequired

    Net, ready to show, such as £12.50.

Errors

  • validation_failed400

    from is after to, the range is longer than 3,660 days, or groupBy=day covers more than 366 days. A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the totals:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 200
{
  "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

GET/api/v1/insights/cash-flow
Needs insights:read

The dashboard's cash flow chart as data: income, spending, net and the running balance of all accounts, one row per day, week or month. Transfers between your own accounts are not counted as flow. balance is the balance at the end of the row. The range is whole UK days.

Query parameters

  • fromstring

    Start of the range: YYYY-MM-DD (that whole UK day) or an ISO 8601 timestamp. Default: 29 days before to.

  • tostring

    End 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) or month.

Response fields

  • startstringrequired

    First UK day of the point inside the range.

  • endstringrequired

    Last UK day of the point inside the range.

  • lineCountintegerrequired

    Ledger lines counted.

  • incomeMinorintegerrequired

    Income, in whole pence.

  • incomeDisplaystringrequired

    Income, ready to show, such as £12.50.

  • spendingMinorintegerrequired

    Spending, in whole pence.

  • spendingDisplaystringrequired

    Spending, ready to show, such as £12.50.

  • netMinorintegerrequired

    Net, in whole pence.

  • netDisplaystringrequired

    Net, ready to show, such as £12.50.

  • balanceMinorintegerrequired

    Balance of all accounts at the end of the point, in whole pence.

  • balanceDisplaystringrequired

    Balance of all accounts at the end of the point, ready to show, such as £12.50.

Errors

  • validation_failed400

    from is after to, the range is longer than 3,660 days, or daily rows cover more than 366 days. A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the insights:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 200
{
  "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

GET/api/v1/insights/spending
Needs insights:read

The dashboard's spending breakdown: the biggest categories or payees by money spent in the range, largest first. Transfers between your own accounts are not counted; refunds reduce what was spent. meta.others adds up everything below limit. sharePercent is the row’s part of meta.totalSpending, which counts every category (or payee) with spending in the range, not only the rows returned, so the shares of the returned rows add up to less than 100 when meta.others is not empty. Spending with no category (or no payee) is one row with id: null and the name Uncategorised (or No payee). The range is whole UK days.

Query parameters

  • fromstring

    Start of the range: YYYY-MM-DD (that whole UK day) or an ISO 8601 timestamp. Default: 29 days before to.

  • tostring

    End 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) or payee.

  • limitinteger

    How many rows, 1 to 100. Default 10.

Response fields

  • idstring | nullrequired

    The category or payee id; null for spending with no category or payee.

  • namestringrequired

    The category or payee name.

  • pathstring | nullrequired

    The category with its parents, such as Home › Bills.

  • sharePercentnumberrequired

    Share of meta.totalSpending (all spending in the range), 0 to 100, one decimal.

  • lineCountintegerrequired

    Ledger lines counted.

  • spendingMinorintegerrequired

    Spending, in whole pence.

  • spendingDisplaystringrequired

    Spending, ready to show, such as £12.50.

Errors

  • validation_failed400

    from is after to, or the range is longer than 3,660 days. A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the insights:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
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'
Response 200
{
  "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

GET/api/v1/insights/net-worth
Needs insights:read

The dashboard's net worth card: the balance of all accounts at the end of to (today by default), what it was before from, and the change between. Credit cards count as negative balances. For the day-by-day line use /insights/cash-flow, whose balance is the same figure.

Query parameters

  • fromstring

    Start of the range: YYYY-MM-DD (that whole UK day) or an ISO 8601 timestamp. Default: 29 days before to.

  • tostring

    End of the range, included: YYYY-MM-DD (that whole UK day) or an ISO 8601 timestamp. Default: today.

Response fields

  • fromstringrequired

    The day the change is measured from.

  • asOfstringrequired

    The balance is as at the end of this day.

  • netWorthMinorintegerrequired

    Net worth, in whole pence.

  • netWorthDisplaystringrequired

    Net worth, ready to show, such as £12.50.

  • openingNetWorthMinorintegerrequired

    Opening net worth, in whole pence.

  • openingNetWorthDisplaystringrequired

    Opening net worth, ready to show, such as £12.50.

  • changeMinorintegerrequired

    Change, in whole pence.

  • changeDisplaystringrequired

    Change, ready to show, such as £12.50.

Errors

  • validation_failed400

    from is after to, or the range is longer than 3,660 days. A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the insights:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/insights/net-worth \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/insights/forecast
Needs insights:read

The Forecast page as data: spendable cash day by day for the next days days after scheduled bills and income, budgets and goal commitments, and the safe-to-spend figure. upperAvailable ignores possible unspent budget; lowerAvailable includes it. Movement amounts are signed (money out is negative). assumptions and missingData say what the numbers rest on.

Query parameters

  • daysnumber

    How far ahead: 7, 14, 30, 60, 90 or 180 days. Default 30.

Response fields

  • todaystringrequired

    Today, in UK time.

  • throughOnstringrequired

    The last day the forecast covers.

  • budgetsEnabledbooleanrequired

    Whether budgets are switched on, so unscheduled budget spending is included.

  • safeToSpendobjectrequired

    What can be spent without leaving a bill uncovered, and how it is made up.

  • safeToSpend.throughOnstringrequired

    The last day counted.

  • safeToSpend.postedCashAccountsobject[]required

    The cash accounts whose posted balances are counted.

  • safeToSpend.keptAsideAccountsobject[]required

    Accounts kept aside, left out of the figures.

  • safeToSpend.startingCashMinorintegerrequired

    Starting cash, in whole pence.

Errors

  • validation_failed400

    days is not 7, 14, 30, 60, 90 or 180. A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the insights:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/insights/forecast?days=30' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/insights/runway
Needs insights:read

The dashboard's cash runway card: spendable cash today (credit cards and Keep aside accounts left out), what is coming in and out over the next 7, 30 and 90 days, and how many days of cover there are before cash first runs out (runwayDays is null when it never does). Overdue items count against the balance from today.

Response fields

  • todaystringrequired

    A UK calendar day, YYYY-MM-DD.

  • runwayDaysinteger | nullrequired

    Whole days of cover before cash first runs out; null if it never does in the next 90 days.

  • firstNegativeOnstring | nullrequired

    The first day cash is projected to go below zero; null if it does not.

  • liquidityRunwayDaysinteger | nullrequired

    The same, counting unused credit.

  • creditUtilisationPercentnumber | nullrequired

    How much of the credit limit is used, as a percentage; null with no credit.

  • workingDayShiftedCountintegerrequired

    How many payments were moved to the next working day.

  • overdueobjectrequired

    Cash already past the day it was due to move. Items that do not change planning cash are left out.

  • overdue.itemCountintegerrequired

    How many bills and payments it covers.

Errors

  • forbidden_scope403

    The key lacks the insights:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/insights/runway \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/summaries
Needs insights:read

The summaries library: one row per period that has a saved summary, newest first. The id is the latest saved version of that period; open it at /summaries/{id}.

Query parameters

  • type"weekly" | "monthly" | "quarterly" | "annual" | "biweekly" | "fourweekly"

    The kind of period: weekly, biweekly, fourweekly, monthly, quarterly or annual. Default monthly.

  • limitinteger

    Rows per page, 1 to 200.

  • cursorstring

    The nextCursor of the previous page.

Response fields

  • idstringrequired

    The id of the latest saved version of this period.

  • type"weekly" | "biweekly" | "fourweekly" | "monthly" | "quarterly" | "annual"required

    The length of the period.

  • periodKeystringrequired

    For example 2026-10 or 2026-W41.

  • periodStartstringrequired

    The first day of the period.

  • periodEndstringrequired

    The last day of the period.

  • partialbooleanrequired

    The version was written while the period was still open.

  • versionintegerrequired

    Which saved version of the period this is; 1 is the first.

  • versionCountintegerrequired

    How many versions of the period are saved.

Errors

  • validation_failed400

    A query parameter is wrong, or not one this endpoint knows; details lists each.

  • forbidden_scope403

    The key lacks the insights:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl 'https://finance.jagwebsites.xyz/api/v1/summaries?type=monthly' \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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

GET/api/v1/summaries/{id}
Needs insights:read

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

  • idstringrequired

    A summary version id from /summaries.

Response fields

  • idstringrequired

    The id of the latest saved version of this period.

  • type"weekly" | "biweekly" | "fourweekly" | "monthly" | "quarterly" | "annual"required

    The length of the period.

  • periodKeystringrequired

    For example 2026-10 or 2026-W41.

  • periodStartstringrequired

    The first day of the period.

  • periodEndstringrequired

    The last day of the period.

  • partialbooleanrequired

    The version was written while the period was still open.

  • versionintegerrequired

    Which saved version of the period this is; 1 is the first.

  • versionCountintegerrequired

    How many versions of the period are saved.

Errors

  • not_found404

    Nothing exists with that id, or it belongs to someone else.

  • forbidden_scope403

    The key lacks the insights:read scope; requiredScope names it.

  • forbidden403

    The key is limited to some accounts, and this area spans all of them (reason: account_limit).

  • unauthorized401

    No API key was sent, or the key is not valid.

  • key_expired401

    The key has passed its expiry date.

  • key_revoked401

    The key was revoked.

  • rate_limited429

    The key has used up its rate limit; wait Retry-After seconds.

Request
curl https://finance.jagwebsites.xyz/api/v1/summaries/sum_1 \
  -H 'Authorization: Bearer sk_your_key'
Response 200
{
  "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"
  }
}