API reference

Pulse

get/v1/pulse

Get the money pulse

pulse.getread tokenidempotent

How much is safe to spend today, with its working: the pay cycle's income, what goes to savings, what was spent, the bills still due and the cash actually on hand. Also what came in and went out since yesterday.

Parameters

X-Organization-Id

string | null · header

Returns 200 · Pulse

bill_count integer · required
bills array of PulseBill · required	The soonest few of those bills, soonest first.
card_balance Money · required	Owed on personal credit cards.
cash_left Money · required	`checking` − `upcoming_bills` − `card_balance`.
checking Money · required	Cash in personal checking accounts counted in totals.
cycle_left Money · required	`income` − `set_aside` − `spent_this_cycle` − `upcoming_bills`.
cycle_start date · required	The last payday, or the period's first day.
days_left integer · required	Days the money has to last, today included; at least 1.
has_cash boolean · required	False when there is no personal checking account to measure; the other figures then mean nothing.
has_income boolean · required	False when there is no income to plan around; `safe_to_spend` is then not a budget and should not be shown as one.
horizon string · required	`payday` or `period_end`: what the cycle runs to.
horizon_date date · required	The next payday (exclusive), or the budget period's last day (inclusive).
income Money · required	Income expected over the whole cycle.
income_source string · required	`paychecks` or `average`: detected paychecks, or the typical month of the last three.
limited_by string · required	`cash_flow` or `cash`: which of the two limits it stopped at.
received_since Money · required
safe_to_spend Money · required	The smaller of `cycle_left` and `cash_left`. Negative when the cycle is already over budget, or bills and cards claim more than is in checking.
safe_today Money · required	`safe_to_spend` over `days_left`, never below zero.
save_share string · required	The default share of income set aside, from 0 to 1, as a decimal string. Pattern: `^\d+(\.\d+)?$`.
set_aside Money · required	Put aside for savings this cycle.
set_aside_source string · required	`share` or `goals`: a share of income, or what the savings goals need, whichever is more.
since date · required	Yesterday: where `spent_since` and `received_since` start.
spent_since Money · required
spent_this_cycle Money · required	Personal spending since the cycle began.
upcoming_bills Money · required	Every bill expected before the horizon.

Example

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

Objects

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

Pulse

Today's money pulse. Personal money only: business accounts and transactions are left out of every term. All amounts are in the ledger's base currency.

Fields

bill_count integer · required
bills array of PulseBill · required	The soonest few of those bills, soonest first.
card_balance Money · required	Owed on personal credit cards.
cash_left Money · required	`checking` − `upcoming_bills` − `card_balance`.
checking Money · required	Cash in personal checking accounts counted in totals.
cycle_left Money · required	`income` − `set_aside` − `spent_this_cycle` − `upcoming_bills`.
cycle_start date · required	The last payday, or the period's first day.
days_left integer · required	Days the money has to last, today included; at least 1.
has_cash boolean · required	False when there is no personal checking account to measure; the other figures then mean nothing.
has_income boolean · required	False when there is no income to plan around; `safe_to_spend` is then not a budget and should not be shown as one.
horizon string · required	`payday` or `period_end`: what the cycle runs to.
horizon_date date · required	The next payday (exclusive), or the budget period's last day (inclusive).
income Money · required	Income expected over the whole cycle.
income_source string · required	`paychecks` or `average`: detected paychecks, or the typical month of the last three.
limited_by string · required	`cash_flow` or `cash`: which of the two limits it stopped at.
received_since Money · required
safe_to_spend Money · required	The smaller of `cycle_left` and `cash_left`. Negative when the cycle is already over budget, or bills and cards claim more than is in checking.
safe_today Money · required	`safe_to_spend` over `days_left`, never below zero.
save_share string · required	The default share of income set aside, from 0 to 1, as a decimal string. Pattern: `^\d+(\.\d+)?$`.
set_aside Money · required	Put aside for savings this cycle.
set_aside_source string · required	`share` or `goals`: a share of income, or what the savings goals need, whichever is more.
since date · required	Yesterday: where `spent_since` and `received_since` start.
spent_since Money · required
spent_this_cycle Money · required	Personal spending since the cycle began.
upcoming_bills Money · required	Every bill expected before the horizon.

PulseBill

Fields

amount Money · required	The usual amount, which is what is expected next.
date date · required	When it is expected.
late boolean · required	The date has passed and it has not arrived; still counted.
merchant_key string · required	The recurring charge (see `recurring.list`).
name string · required