API reference

Categories

post/v1/categories

Create a category

categories.createwrite tokenidempotent

Create an income or expense category to file transactions under. Its code is allocated for you, and it is nested under its type's group, or under parent_id as a subcategory (one level deep). Returns it as an account, the shape every category has on this API. Send an Idempotency-Key so a retry cannot create it twice.

Parameters

Idempotency-Key string \| null · header	Any unique string (a UUID is ideal). A retry with the same key returns the first attempt's response instead of doing the work twice. Keys are kept for 24 hours.
X-Organization-Id string \| null · header

Body · CategoryCreate

name string · required
parent_id integer \| null	Make it a subcategory of this top-level category of the same type (an account id from `accounts.list?type=expense`). Omitted, it is a top-level category.
type string · required	`expense` for spending, `income` for money coming in. Pattern: `^(expense\|income)$`.

Returns 201 · Account

balance Money · required	The account's balance, positive on its normal side: what an asset holds, what a liability owes, what an expense category has spent in total.
code string · required	Chart-of-accounts code, unique in the ledger (`1010`, `5190`).
created_at datetime · required
excluded_from_totals boolean · required	Left out of net worth and other totals.
hidden boolean · required	Hidden from lists in the app.
id integer · required	The account id. Transactions and journal lines name it as `account_id`.
institution_id integer \| null · required	The bank or provider the account belongs to.
is_active boolean · required	False once the account is closed. Its history stays in the ledger.
is_placeholder boolean · required	A grouping account that holds no postings of its own.
low_balance_alert LowBalanceAlert \| null · required	The member is told when this account's balance drops below a threshold, and has a to-do until it is back above; null when nobody set one. Only an open asset account can carry one. Set it with `accounts.update`.
mask string \| null · required	The last digits of the account number, as the bank shows them.
name string · required
normal_balance string · required	`debit` or `credit`: the side that increases the account.
overdraft_ahead LowBalanceShortfall \| null · required	With no `low_balance_alert` set: the recurring bills and paychecks expected on this open asset account over the next month, and the payments of the credit cards it pays, take its balance below zero; `needed` is what to move in to stay at or above zero. The member sees it on their to-do list and the account's page but is never notified of it unasked: setting a `low_balance_alert` is how they ask. Null when the bills ahead do not, when the balance is already below zero, and whenever an alert is set (its `shortfall` says it then).
parent_id integer \| null · required	The parent account, for sub-accounts and subcategories.
purpose string \| null · required	`business` if its transactions count as business by default; null for personal.
role string \| null · required	What the account is for, when known (`checking`, `credit_card`, `mortgage`, …).
type string · required	`asset`, `liability`, `equity`, `income` or `expense`.
unshared_at datetime \| null · required	When the bank stopped sharing this account on its connection (deselected, closed or revoked at the bank) while the connection itself keeps syncing, or null while it is shared. Its `balance` is frozen at the last number the bank sent. A person fixes it in the app by sharing the account again, or closes it with `accounts.close`.

Example

curl -X POST "https://api.lumaledger.app/v1/categories" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "…",
    "type": "…"
  }'

Objects

Account

One account in the ledger's chart of accounts: a bank account, a card, a loan, or a category such as Groceries (an expense account).

Fields

balance Money · required	The account's balance, positive on its normal side: what an asset holds, what a liability owes, what an expense category has spent in total.
code string · required	Chart-of-accounts code, unique in the ledger (`1010`, `5190`).
created_at datetime · required
excluded_from_totals boolean · required	Left out of net worth and other totals.
hidden boolean · required	Hidden from lists in the app.
id integer · required	The account id. Transactions and journal lines name it as `account_id`.
institution_id integer \| null · required	The bank or provider the account belongs to.
is_active boolean · required	False once the account is closed. Its history stays in the ledger.
is_placeholder boolean · required	A grouping account that holds no postings of its own.
low_balance_alert LowBalanceAlert \| null · required	The member is told when this account's balance drops below a threshold, and has a to-do until it is back above; null when nobody set one. Only an open asset account can carry one. Set it with `accounts.update`.
mask string \| null · required	The last digits of the account number, as the bank shows them.
name string · required
normal_balance string · required	`debit` or `credit`: the side that increases the account.
overdraft_ahead LowBalanceShortfall \| null · required	With no `low_balance_alert` set: the recurring bills and paychecks expected on this open asset account over the next month, and the payments of the credit cards it pays, take its balance below zero; `needed` is what to move in to stay at or above zero. The member sees it on their to-do list and the account's page but is never notified of it unasked: setting a `low_balance_alert` is how they ask. Null when the bills ahead do not, when the balance is already below zero, and whenever an alert is set (its `shortfall` says it then).
parent_id integer \| null · required	The parent account, for sub-accounts and subcategories.
purpose string \| null · required	`business` if its transactions count as business by default; null for personal.
role string \| null · required	What the account is for, when known (`checking`, `credit_card`, `mortgage`, …).
type string · required	`asset`, `liability`, `equity`, `income` or `expense`.
unshared_at datetime \| null · required	When the bank stopped sharing this account on its connection (deselected, closed or revoked at the bank) while the connection itself keeps syncing, or null while it is shared. Its `balance` is frozen at the last number the bank sent. A person fixes it in the app by sharing the account again, or closes it with `accounts.close`.

CategoryCreate

Fields

name string · required
parent_id integer \| null	Make it a subcategory of this top-level category of the same type (an account id from `accounts.list?type=expense`). Omitted, it is a top-level category.
type string · required	`expense` for spending, `income` for money coming in. Pattern: `^(expense\|income)$`.

LowBalanceAlert

"Tell me when this account drops below …".

Fields

below boolean · required	The balance is under the threshold right now.
below_since datetime \| null · required	When the balance was seen dropping below the threshold, which is when the member was notified; null while it is at or above it.
shortfall LowBalanceShortfall \| null · required	The recurring bills and paychecks expected on the account over the next month, and the payments of the credit cards it pays (bills first on a day), take the balance under the threshold; the member is notified once and has a to-do while it stands. Null when they do not, and while the balance is already below.
threshold Money · required	Alert when the balance drops below this.

LowBalanceShortfall

The recurring bills and paychecks expected on the account over the next month take its balance under the alert's threshold.

Fields

bill_amount Money · required	That bill's usual amount; for a card, what paying it in full takes.
bill_kind string · required	`recurring`: a charge the recurring detector found. `card_payment`: a credit card this account paid last, expected to be paid in full by its due date.
bill_name string · required	The expected bill that takes it under: a recurring charge's name, or the name of the credit card whose payment it is.
lowest Money · required	The lowest the balance is projected to reach over the month.
needed Money · required	What to move in now to stay at or above the threshold all month.
short_on date · required	The first day the balance is projected under the threshold.

Money

An amount and its currency. `amount` is a base-10 string with two decimal places and an optional leading minus sign. Parse it with a decimal type, not a float.

Fields

amount string · required	Pattern: `^-?\d+\.\d{2}$`.
currency string · required	ISO 4217 code. Pattern: `^[A-Z]{3}$`.