API reference

Counterparties

get/v1/counterparties

List counterparties

counterparties.listread tokenidempotent

Everyone the ledger paid or was paid by in the window, with totals each way and how their transactions are filed. Counterparties are derived from transactions when asked, so a page is computed from the whole window each time.

Parameters

limit integer · query	Page size, 1–200.
cursor string \| null · query	The `next_cursor` of the previous page.
lookback_days integer · query	Only counterparties with transactions in this many days, and totals over them.
X-Organization-Id string \| null · header

Returns 200 · CounterpartyList

data array of Counterparty · required
has_more boolean · required
next_cursor string \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/counterparties" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/counterparties/{counterparty_key}

Get a counterparty

counterparties.getread tokenidempotent

One counterparty over all time: totals, its rules, what the web lookup found, money per month and its latest transactions.

Parameters

counterparty_key string · path · required
X-Organization-Id string \| null · header

Returns 200 · CounterpartyDetails

about CounterpartyAbout \| null · required	The lookup's answer; null when never looked up.
about_edits CounterpartyAboutEdits \| null · required
about_summary string \| null · required	One line on who it is, when it has been identified.
average_amount Money · required	The average transaction, as a positive amount.
category_id integer \| null · required	The category its transactions are filed under, when there is one.
confidence string · required	How sure the ledger is about where its transactions are filed, 0 to 1, as a decimal string. Pattern: `^[01]\.\d{4}$`.
confidence_band string · required	`sure`, `unsure` or `unfiled`.
counterparty_type string \| null · required	`merchant`, `financial_institution`, `income_source`, `payment_app`, `marketplace`, … Null when unknown.
customized boolean · required	The user renamed it or gave it a logo.
derived_name string · required	The name before any rename.
descriptions array of string · required	Distinct descriptions the bank has used for it (at most 12).
direction string · required	`out` (you pay it), `in` (it pays you) or `both`.
first_date date · required
has_rule boolean · required	A standing rule, not a guess, decides where its transactions go.
key string · required	The counterparty key: its id. See the resource description.
last_date date · required
logo_url string \| null · required
merchant_entity_id string \| null · required	The bank data provider's id for the merchant, when it has one.
merged_from array of MergedCounterparty · required	Counterparties merged into this one (`counterparties.merge`), oldest merge first.
mixed boolean · required	Its past transactions sit in more than one category.
monthly array of CounterpartyMonth · required	Paid and received per month, oldest first.
name string · required	What to call it: the user's name for it, else the one derived from the bank's descriptions.
notes string \| null · required
pattern string · required	The description text a rule for it matches on.
recent_transactions array of CounterpartyTransaction · required	Its latest 50 transactions, newest first.
rule_count integer · required
rules array of CounterpartyRule · required
seller_unknown boolean · required	Every transaction names only an intermediary (a marketplace, a wallet).
suggested_pattern string · required	The pattern a new rule would match on by default.
suggests_transfer boolean · required	Looks like money between the user's own accounts, and nothing is decided yet.
total_moved Money · required	Moved to or from the ledger's own accounts in its transactions filed as transfers (`recent_transactions[].transfer_account_id`), as a positive amount. Never part of `total_paid` or `total_received`.
total_paid Money · required	Paid to it, as a positive amount.
total_received Money · required	Received from it, as a positive amount.
transaction_count integer · required
transfer_account_id integer \| null · required	Set instead of `category_id` when its transactions are transfers to one of the ledger's own accounts (a card payment, a savings sweep).
website string \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/counterparties/{counterparty_key}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

patch/v1/counterparties/{counterparty_key}

Update a counterparty

counterparties.updatewrite tokenidempotent

Rename a counterparty, give it a logo or a note, or correct what its About card says. Only the fields sent change. Its key does not change: the name is an overlay on what the bank sends.

Parameters

counterparty_key string · path · required
X-Organization-Id string \| null · header

Body · CounterpartyUpdate

about_description string \| null
about_summary string \| null
address string \| null
display_name string \| null
logo_url string \| null
notes string \| null
phone string \| null
website string \| null

Returns 200 · CounterpartyDetails

about CounterpartyAbout \| null · required	The lookup's answer; null when never looked up.
about_edits CounterpartyAboutEdits \| null · required
about_summary string \| null · required	One line on who it is, when it has been identified.
average_amount Money · required	The average transaction, as a positive amount.
category_id integer \| null · required	The category its transactions are filed under, when there is one.
confidence string · required	How sure the ledger is about where its transactions are filed, 0 to 1, as a decimal string. Pattern: `^[01]\.\d{4}$`.
confidence_band string · required	`sure`, `unsure` or `unfiled`.
counterparty_type string \| null · required	`merchant`, `financial_institution`, `income_source`, `payment_app`, `marketplace`, … Null when unknown.
customized boolean · required	The user renamed it or gave it a logo.
derived_name string · required	The name before any rename.
descriptions array of string · required	Distinct descriptions the bank has used for it (at most 12).
direction string · required	`out` (you pay it), `in` (it pays you) or `both`.
first_date date · required
has_rule boolean · required	A standing rule, not a guess, decides where its transactions go.
key string · required	The counterparty key: its id. See the resource description.
last_date date · required
logo_url string \| null · required
merchant_entity_id string \| null · required	The bank data provider's id for the merchant, when it has one.
merged_from array of MergedCounterparty · required	Counterparties merged into this one (`counterparties.merge`), oldest merge first.
mixed boolean · required	Its past transactions sit in more than one category.
monthly array of CounterpartyMonth · required	Paid and received per month, oldest first.
name string · required	What to call it: the user's name for it, else the one derived from the bank's descriptions.
notes string \| null · required
pattern string · required	The description text a rule for it matches on.
recent_transactions array of CounterpartyTransaction · required	Its latest 50 transactions, newest first.
rule_count integer · required
rules array of CounterpartyRule · required
seller_unknown boolean · required	Every transaction names only an intermediary (a marketplace, a wallet).
suggested_pattern string · required	The pattern a new rule would match on by default.
suggests_transfer boolean · required	Looks like money between the user's own accounts, and nothing is decided yet.
total_moved Money · required	Moved to or from the ledger's own accounts in its transactions filed as transfers (`recent_transactions[].transfer_account_id`), as a positive amount. Never part of `total_paid` or `total_received`.
total_paid Money · required	Paid to it, as a positive amount.
total_received Money · required	Received from it, as a positive amount.
transaction_count integer · required
transfer_account_id integer \| null · required	Set instead of `category_id` when its transactions are transfers to one of the ledger's own accounts (a card payment, a savings sweep).
website string \| null · required

Example

curl -X PATCH "https://api.lumaledger.app/v1/counterparties/{counterparty_key}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

get/v1/counterparties/{counterparty_key}/about

Get who a counterparty is

counterparties.get_aboutread tokenidempotent

The stored answer to "who is this?", and whether a lookup is still running (poll this after counterparties.identify).

Parameters

counterparty_key string · path · required
X-Organization-Id string \| null · header

Returns 200 · CounterpartyAboutResult

about CounterpartyAbout \| null · required
pending boolean · required	A lookup is running; poll `counterparties.get_about` until this is false.

Example

curl -X GET "https://api.lumaledger.app/v1/counterparties/{counterparty_key}/about" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

post/v1/counterparties/{counterparty_key}/category

File a counterparty under a category or mark it a transfer

counterparties.set_categorywrite tokenidempotent

Give a counterparty a standing rule: file its transactions under category_id, or treat them as transfers to one of the ledger's own accounts (transfer_account_id: a card payment, a savings sweep). With backfill its past transactions move too. Send neither to drop the rule; transactions keep where they are.

Parameters

counterparty_key string · path · required
X-Organization-Id string \| null · header

Body · CounterpartyCategoryInput

backfill boolean	Also refile the transactions already in the ledger. Default: `true`.
category_id integer \| null	An income or expense account (see `accounts.list`).
transfer_account_id integer \| null	One of the ledger's own accounts: its transactions become transfers there.

Returns 200 · CounterpartyCategoryResult

cleared boolean · required	A standing rule was dropped (neither target was sent).
moved integer · required	Past transactions refiled.

Example

curl -X POST "https://api.lumaledger.app/v1/counterparties/{counterparty_key}/category" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

post/v1/counterparties/{counterparty_key}/identify

Look up who a counterparty is

counterparties.identifywrite tokenidempotent

Search the web for who a counterparty is, and keep the answer. A counterparty already identified returns what is stored without searching again, so this is safe to call on every read. When the search runs in the background pending is true: poll counterparties.get_about. Answers 503 when lookups are not configured on this server.

Parameters

counterparty_key string · path · required
X-Organization-Id string \| null · header

Returns 200 · CounterpartyAboutResult

about CounterpartyAbout \| null · required
pending boolean · required	A lookup is running; poll `counterparties.get_about` until this is false.

Example

curl -X POST "https://api.lumaledger.app/v1/counterparties/{counterparty_key}/identify" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

delete/v1/counterparties/{counterparty_key}/merge

Separate a merged counterparty

counterparties.unmergewrite tokenidempotent

Undo counterparties.merge for this key (one of the target's merged_from): its transactions group on their own again.

Parameters

counterparty_key string · path · required
X-Organization-Id string \| null · header

Returns 204 with no body.

Example

curl -X DELETE "https://api.lumaledger.app/v1/counterparties/{counterparty_key}/merge" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

post/v1/counterparties/{counterparty_key}/merge

Merge a counterparty into another

counterparties.mergewrite tokenidempotent

Treat this counterparty as part of target_key: its transactions, past and future, group under the target, and its own key stops resolving. Nothing is refiled — who a transaction is with changes, not what it was for. Returns the target as it now stands; undo with counterparties.unmerge.

Parameters

counterparty_key string · path · required
X-Organization-Id string \| null · header

Body · CounterpartyMergeInput

target_key

string · required

The counterparty to fold this one into — a key from counterparties.list.

Returns 200 · CounterpartyDetails

about CounterpartyAbout \| null · required	The lookup's answer; null when never looked up.
about_edits CounterpartyAboutEdits \| null · required
about_summary string \| null · required	One line on who it is, when it has been identified.
average_amount Money · required	The average transaction, as a positive amount.
category_id integer \| null · required	The category its transactions are filed under, when there is one.
confidence string · required	How sure the ledger is about where its transactions are filed, 0 to 1, as a decimal string. Pattern: `^[01]\.\d{4}$`.
confidence_band string · required	`sure`, `unsure` or `unfiled`.
counterparty_type string \| null · required	`merchant`, `financial_institution`, `income_source`, `payment_app`, `marketplace`, … Null when unknown.
customized boolean · required	The user renamed it or gave it a logo.
derived_name string · required	The name before any rename.
descriptions array of string · required	Distinct descriptions the bank has used for it (at most 12).
direction string · required	`out` (you pay it), `in` (it pays you) or `both`.
first_date date · required
has_rule boolean · required	A standing rule, not a guess, decides where its transactions go.
key string · required	The counterparty key: its id. See the resource description.
last_date date · required
logo_url string \| null · required
merchant_entity_id string \| null · required	The bank data provider's id for the merchant, when it has one.
merged_from array of MergedCounterparty · required	Counterparties merged into this one (`counterparties.merge`), oldest merge first.
mixed boolean · required	Its past transactions sit in more than one category.
monthly array of CounterpartyMonth · required	Paid and received per month, oldest first.
name string · required	What to call it: the user's name for it, else the one derived from the bank's descriptions.
notes string \| null · required
pattern string · required	The description text a rule for it matches on.
recent_transactions array of CounterpartyTransaction · required	Its latest 50 transactions, newest first.
rule_count integer · required
rules array of CounterpartyRule · required
seller_unknown boolean · required	Every transaction names only an intermediary (a marketplace, a wallet).
suggested_pattern string · required	The pattern a new rule would match on by default.
suggests_transfer boolean · required	Looks like money between the user's own accounts, and nothing is decided yet.
total_moved Money · required	Moved to or from the ledger's own accounts in its transactions filed as transfers (`recent_transactions[].transfer_account_id`), as a positive amount. Never part of `total_paid` or `total_received`.
total_paid Money · required	Paid to it, as a positive amount.
total_received Money · required	Received from it, as a positive amount.
transaction_count integer · required
transfer_account_id integer \| null · required	Set instead of `category_id` when its transactions are transfers to one of the ledger's own accounts (a card payment, a savings sweep).
website string \| null · required

Example

curl -X POST "https://api.lumaledger.app/v1/counterparties/{counterparty_key}/merge" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_key": "…"
  }'

post/v1/counterparties/{counterparty_key}/rules

Add a rule for a counterparty

counterparties.create_rulewrite tokenidempotent

Add a rule narrower than the counterparty's default: "over 200 from this store is Equipment, the rest stays Supplies". With backfill, its matching past transactions are refiled now.

Parameters

counterparty_key string · path · required
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 · CounterpartyRuleInput

amount_max string \| null	Positive decimal string. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
amount_min string \| null	Positive decimal string. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
backfill boolean	Also refile matching transactions already in the ledger. Default: `true`.
category_id integer · required	The income or expense account to file matching transactions under.
match_entity boolean	Also match on the provider's merchant id. Default: `true`.
pattern string \| null	Description text to match; defaults to the counterparty's own pattern.

Returns 201 · CounterpartyRuleResult

moved integer · required	Past transactions refiled.
rule CounterpartyRule · required

Example

curl -X POST "https://api.lumaledger.app/v1/counterparties/{counterparty_key}/rules" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": 1
  }'

delete/v1/counterparties/{counterparty_key}/rules/{counterparty_rule_id}

Delete a counterparty rule

counterparties.delete_rulewrite tokendestructiveidempotent

Delete one of a counterparty's rules (ids from counterparties.get) and refile its transactions under whatever governs them next.

Parameters

counterparty_key string · path · required
counterparty_rule_id integer · path · required
X-Organization-Id string \| null · header

Returns 204 with no body.

Example

curl -X DELETE "https://api.lumaledger.app/v1/counterparties/{counterparty_key}/rules/{counterparty_rule_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

Objects

AboutSource

Fields

title string · required
url string · required

Counterparty

A merchant, employer, person or bank the ledger has transactions with, and how its transactions are filed.

Fields

about_summary string \| null · required	One line on who it is, when it has been identified.
average_amount Money · required	The average transaction, as a positive amount.
category_id integer \| null · required	The category its transactions are filed under, when there is one.
confidence string · required	How sure the ledger is about where its transactions are filed, 0 to 1, as a decimal string. Pattern: `^[01]\.\d{4}$`.
confidence_band string · required	`sure`, `unsure` or `unfiled`.
counterparty_type string \| null · required	`merchant`, `financial_institution`, `income_source`, `payment_app`, `marketplace`, … Null when unknown.
customized boolean · required	The user renamed it or gave it a logo.
direction string · required	`out` (you pay it), `in` (it pays you) or `both`.
first_date date · required
has_rule boolean · required	A standing rule, not a guess, decides where its transactions go.
key string · required	The counterparty key: its id. See the resource description.
last_date date · required
logo_url string \| null · required
merchant_entity_id string \| null · required	The bank data provider's id for the merchant, when it has one.
mixed boolean · required	Its past transactions sit in more than one category.
name string · required	What to call it: the user's name for it, else the one derived from the bank's descriptions.
pattern string · required	The description text a rule for it matches on.
rule_count integer · required
seller_unknown boolean · required	Every transaction names only an intermediary (a marketplace, a wallet).
suggests_transfer boolean · required	Looks like money between the user's own accounts, and nothing is decided yet.
total_paid Money · required	Paid to it, as a positive amount.
total_received Money · required	Received from it, as a positive amount.
transaction_count integer · required
transfer_account_id integer \| null · required	Set instead of `category_id` when its transactions are transfers to one of the ledger's own accounts (a card payment, a savings sweep).

CounterpartyAbout

Who a counterparty is, as looked up on the web.

Fields

address string \| null · required
description string \| null · required
looked_up_at datetime · required
phone string \| null · required
sources array of AboutSource · required
status string · required	`found`, or `unknown` when the lookup could not tell.
summary string \| null · required
website string \| null · required

CounterpartyAboutEdits

The user's corrections to the About card, field by field. Null shows what the lookup found; an empty string shows nothing.

Fields

address string \| null · required
description string \| null · required
phone string \| null · required
summary string \| null · required
website string \| null · required

CounterpartyAboutResult

Fields

about CounterpartyAbout \| null · required
pending boolean · required	A lookup is running; poll `counterparties.get_about` until this is false.

CounterpartyCategoryInput

Where the counterparty's transactions go. Send category_id or transfer_account_id, or neither to drop its standing rule.

Fields

backfill boolean	Also refile the transactions already in the ledger. Default: `true`.
category_id integer \| null	An income or expense account (see `accounts.list`).
transfer_account_id integer \| null	One of the ledger's own accounts: its transactions become transfers there.

CounterpartyCategoryResult

Fields

cleared boolean · required	A standing rule was dropped (neither target was sent).
moved integer · required	Past transactions refiled.

CounterpartyDetails

A counterparty in full, over all time (the list is windowed).

Fields

about CounterpartyAbout \| null · required	The lookup's answer; null when never looked up.
about_edits CounterpartyAboutEdits \| null · required
about_summary string \| null · required	One line on who it is, when it has been identified.
average_amount Money · required	The average transaction, as a positive amount.
category_id integer \| null · required	The category its transactions are filed under, when there is one.
confidence string · required	How sure the ledger is about where its transactions are filed, 0 to 1, as a decimal string. Pattern: `^[01]\.\d{4}$`.
confidence_band string · required	`sure`, `unsure` or `unfiled`.
counterparty_type string \| null · required	`merchant`, `financial_institution`, `income_source`, `payment_app`, `marketplace`, … Null when unknown.
customized boolean · required	The user renamed it or gave it a logo.
derived_name string · required	The name before any rename.
descriptions array of string · required	Distinct descriptions the bank has used for it (at most 12).
direction string · required	`out` (you pay it), `in` (it pays you) or `both`.
first_date date · required
has_rule boolean · required	A standing rule, not a guess, decides where its transactions go.
key string · required	The counterparty key: its id. See the resource description.
last_date date · required
logo_url string \| null · required
merchant_entity_id string \| null · required	The bank data provider's id for the merchant, when it has one.
merged_from array of MergedCounterparty · required	Counterparties merged into this one (`counterparties.merge`), oldest merge first.
mixed boolean · required	Its past transactions sit in more than one category.
monthly array of CounterpartyMonth · required	Paid and received per month, oldest first.
name string · required	What to call it: the user's name for it, else the one derived from the bank's descriptions.
notes string \| null · required
pattern string · required	The description text a rule for it matches on.
recent_transactions array of CounterpartyTransaction · required	Its latest 50 transactions, newest first.
rule_count integer · required
rules array of CounterpartyRule · required
seller_unknown boolean · required	Every transaction names only an intermediary (a marketplace, a wallet).
suggested_pattern string · required	The pattern a new rule would match on by default.
suggests_transfer boolean · required	Looks like money between the user's own accounts, and nothing is decided yet.
total_moved Money · required	Moved to or from the ledger's own accounts in its transactions filed as transfers (`recent_transactions[].transfer_account_id`), as a positive amount. Never part of `total_paid` or `total_received`.
total_paid Money · required	Paid to it, as a positive amount.
total_received Money · required	Received from it, as a positive amount.
transaction_count integer · required
transfer_account_id integer \| null · required	Set instead of `category_id` when its transactions are transfers to one of the ledger's own accounts (a card payment, a savings sweep).
website string \| null · required

CounterpartyList

A page of counterparties, in key order.

Fields

data array of Counterparty · required
has_more boolean · required
next_cursor string \| null · required

CounterpartyMergeInput

Fields

target_key

string · required

The counterparty to fold this one into — a key from counterparties.list.

CounterpartyMonth

Fields

month string · required	`YYYY-MM`.
paid Money · required
received Money · required

CounterpartyRule

A standing rule that files a counterparty's transactions.

Fields

amount_max Money \| null · required	Only transactions of at most this much.
amount_min Money \| null · required	Only transactions of at least this much.
category_id integer \| null · required
id integer · required	The rule id (`counterparty_rule_id`).
matches_entity boolean · required	Also matches on the provider's merchant id, exactly.
pattern string · required	Description text the rule matches (uppercase).
source string · required	`manual` (someone wrote it) or `learned`.
transfer_account_id integer \| null · required

CounterpartyRuleInput

A rule narrower than the counterparty's default: a pattern, an amount band, or both. Writing one with the same pattern and band as an existing rule replaces that rule's category.

Fields

amount_max string \| null	Positive decimal string. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
amount_min string \| null	Positive decimal string. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
backfill boolean	Also refile matching transactions already in the ledger. Default: `true`.
category_id integer · required	The income or expense account to file matching transactions under.
match_entity boolean	Also match on the provider's merchant id. Default: `true`.
pattern string \| null	Description text to match; defaults to the counterparty's own pattern.

CounterpartyRuleResult

Fields

moved integer · required	Past transactions refiled.
rule CounterpartyRule · required

CounterpartyTransaction

Fields

amount Money · required	Always positive; `direction` says which way it moved.
category_id integer \| null · required
date date · required
description string · required
direction string · required	`out` or `in`.
transaction_id integer \| null · required	The transaction id for `transactions.get`; null while it has not posted to the ledger.
transfer_account_id integer \| null · required	Set instead of `category_id` when the transaction was filed, by hand or by a rule, as a transfer to or from one of the ledger's own accounts.

CounterpartyUpdate

Only the fields sent change. null goes back to what was derived (for display_name, logo_url, notes) or found by the lookup (for the About fields); an empty About field hides it. URLs must be http(s).

Fields

about_description string \| null
about_summary string \| null
address string \| null
display_name string \| null
logo_url string \| null
notes string \| null
phone string \| null
website string \| null

MergedCounterparty

Fields

key string · required	The key it had on its own; pass it to `counterparties.unmerge`.
name string · required	What it was called when it was merged.

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}$`.

about_description string \| null
about_summary string \| null
address string \| null
display_name string \| null
logo_url string \| null
notes string \| null
phone string \| null
website string \| null

address string \| null · required
description string \| null · required
looked_up_at datetime · required
phone string \| null · required
sources array of AboutSource · required
status string · required	`found`, or `unknown` when the lookup could not tell.
summary string \| null · required
website string \| null · required

address string \| null · required
description string \| null · required
phone string \| null · required
summary string \| null · required
website string \| null · required

about_description string \| null
about_summary string \| null
address string \| null
display_name string \| null
logo_url string \| null
notes string \| null
phone string \| null
website string \| null