Loans
/v1/loansList loans
Every loan in the ledger except dismissed ones, with today's balance
and, where the terms allow, when it will be paid off. Suggested loans
(found from the bank, not yet confirmed) are listed too; they post
nothing until confirmed with loans.set_status.
Parameters
limit integer · query | Page size, 1–200. |
cursor string | null · query | The next_cursor of the previous page. |
X-Organization-Id string | null · header |
Returns 200 · LoanList
data | |
has_more boolean · required | |
next_cursor string | null · required |
curl -X GET "https://api.lumaledger.app/v1/loans" \
-H "Authorization: Bearer $LUMALEDGER_TOKEN"/v1/loansCreate a loan
Record a loan's terms against its liability account. A confirmed
amortizing or accrue-only loan gets a standing order that posts its
interest (and its payments) every period from then on. 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 · LoanCreate
accrual_mode string · required | One of accrue_only, amortizing, statement. |
annual_rate string | null | Annual rate in percent, as a decimal string: "6.125". 0–200. Pattern: ^\d{1,3}(\.\d{1,4})?$. |
day_count string | One of act365, act360, thirty360. Default: "act365". |
escrow_account_id integer | null | Where the escrow share goes. |
escrow_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
interest_account_id integer | null | Expense account for interest. |
kind string · required | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer · required | The liability account that holds the balance (see accounts.list). One loan per account. |
maturity_date date | null | |
name string · required | |
original_principal string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
origination_date date | null | |
payable_account_id integer | null | Liability for accrued interest (accrue_only). Must not be the loan's own account. |
payment_account_id integer | null | The account payments leave from. |
payment_amount string | null | The regular payment, escrow included. Pattern: ^\d{1,12}(\.\d{1,2})?$. |
payment_cadence string | One of weekly, monthly, quarterly, annually. Default: "monthly". |
payment_day integer | null | 1–28, or -1 for the month's last day. |
rate_type string | fixed or variable. Default: "fixed". |
term_months integer | null | 1–1200. |
Returns 201 · LoanDetail
accrual_mode string · required | amortizing: a level payment posts each period and splits into interest and principal. accrue_only: interest accrues to a payable, no payments are modelled. statement: the servicer reports the interest and the ledger never computes it. |
annual_rate string | null · required | Annual interest rate in percent, as a decimal string: "6.125". |
balance Money · required | What is owed today: the liability account's balance, positive while owed. |
day_count string · required | How a period's interest counts days: act365, act360, thirty360. |
escrow_account_id integer | null · required | The account the escrow share of a payment goes to. |
escrow_amount | The escrow share of each payment. |
id integer · required | |
interest_account_id integer | null · required | The expense account interest posts to. |
kind string · required | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer · required | The liability account that holds the balance. |
maturity_date date | null · required | |
name string · required | |
original_principal | |
origination_date date | null · required | |
payable_account_id integer | null · required | The liability accrued interest posts to (accrue_only loans). |
payment_account_id integer | null · required | The account payments leave from. |
payment_amount | The regular payment, escrow included. |
payment_cadence string · required | One of weekly, monthly, quarterly, annually. |
payment_day integer | null · required | Day of the month payments fall on, 1–28, or -1 for the month's last day. |
projection | Null when the terms cannot be projected (not amortizing, or no payment or rate). |
rate_type string · required | fixed or variable. |
schedule | Every remaining period until payoff, capped at 600. Empty when there is no projection. |
scheduled_entry_id integer | null · required | The standing order that posts the loan's interest and payments, when it has one. |
source string · required | manual, inferred (from the bank) or assistant. |
status string · required | suggested (inferred from the bank, awaiting a verdict), confirmed, closed or dismissed. Only confirmed loans post and count in plans. |
term_months integer | null · required |
curl -X POST "https://api.lumaledger.app/v1/loans" \
-H "Authorization: Bearer $LUMALEDGER_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"accrual_mode": "…",
"kind": "…",
"liability_account_id": 1,
"name": "…"
}'/v1/loans/{loan_id}Delete a loan
Delete a loan's terms and its standing order. The liability account and everything already posted to it stay in the ledger.
Parameters
loan_id integer · path · required | |
X-Organization-Id string | null · header |
Returns 204 with no body.
curl -X DELETE "https://api.lumaledger.app/v1/loans/{loan_id}" \
-H "Authorization: Bearer $LUMALEDGER_TOKEN"/v1/loans/{loan_id}Get a loan
One loan with its amortization table, recomputed from today's balance: every remaining period's interest, principal and escrow until the balance reaches zero.
Parameters
loan_id integer · path · required | |
X-Organization-Id string | null · header |
Returns 200 · LoanDetail
accrual_mode string · required | amortizing: a level payment posts each period and splits into interest and principal. accrue_only: interest accrues to a payable, no payments are modelled. statement: the servicer reports the interest and the ledger never computes it. |
annual_rate string | null · required | Annual interest rate in percent, as a decimal string: "6.125". |
balance Money · required | What is owed today: the liability account's balance, positive while owed. |
day_count string · required | How a period's interest counts days: act365, act360, thirty360. |
escrow_account_id integer | null · required | The account the escrow share of a payment goes to. |
escrow_amount | The escrow share of each payment. |
id integer · required | |
interest_account_id integer | null · required | The expense account interest posts to. |
kind string · required | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer · required | The liability account that holds the balance. |
maturity_date date | null · required | |
name string · required | |
original_principal | |
origination_date date | null · required | |
payable_account_id integer | null · required | The liability accrued interest posts to (accrue_only loans). |
payment_account_id integer | null · required | The account payments leave from. |
payment_amount | The regular payment, escrow included. |
payment_cadence string · required | One of weekly, monthly, quarterly, annually. |
payment_day integer | null · required | Day of the month payments fall on, 1–28, or -1 for the month's last day. |
projection | Null when the terms cannot be projected (not amortizing, or no payment or rate). |
rate_type string · required | fixed or variable. |
schedule | Every remaining period until payoff, capped at 600. Empty when there is no projection. |
scheduled_entry_id integer | null · required | The standing order that posts the loan's interest and payments, when it has one. |
source string · required | manual, inferred (from the bank) or assistant. |
status string · required | suggested (inferred from the bank, awaiting a verdict), confirmed, closed or dismissed. Only confirmed loans post and count in plans. |
term_months integer | null · required |
curl -X GET "https://api.lumaledger.app/v1/loans/{loan_id}" \
-H "Authorization: Bearer $LUMALEDGER_TOKEN"/v1/loans/{loan_id}Update a loan
Change a loan's terms. Only the fields sent change, and the standing order is rewritten from the result, so the next posting follows the new terms.
Parameters
loan_id integer · path · required | |
X-Organization-Id string | null · header |
Body · LoanUpdate
accrual_mode string | One of accrue_only, amortizing, statement. |
annual_rate string | null | Pattern: ^\d{1,3}(\.\d{1,4})?$. |
day_count string | One of act365, act360, thirty360. |
escrow_account_id integer | null | |
escrow_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
interest_account_id integer | null | |
kind string | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer | |
maturity_date date | null | |
name string | |
original_principal string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
origination_date date | null | |
payable_account_id integer | null | |
payment_account_id integer | null | |
payment_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
payment_cadence string | One of weekly, monthly, quarterly, annually. |
payment_day integer | null | |
rate_type string | fixed or variable. |
term_months integer | null | 1–1200. |
Returns 200 · LoanDetail
accrual_mode string · required | amortizing: a level payment posts each period and splits into interest and principal. accrue_only: interest accrues to a payable, no payments are modelled. statement: the servicer reports the interest and the ledger never computes it. |
annual_rate string | null · required | Annual interest rate in percent, as a decimal string: "6.125". |
balance Money · required | What is owed today: the liability account's balance, positive while owed. |
day_count string · required | How a period's interest counts days: act365, act360, thirty360. |
escrow_account_id integer | null · required | The account the escrow share of a payment goes to. |
escrow_amount | The escrow share of each payment. |
id integer · required | |
interest_account_id integer | null · required | The expense account interest posts to. |
kind string · required | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer · required | The liability account that holds the balance. |
maturity_date date | null · required | |
name string · required | |
original_principal | |
origination_date date | null · required | |
payable_account_id integer | null · required | The liability accrued interest posts to (accrue_only loans). |
payment_account_id integer | null · required | The account payments leave from. |
payment_amount | The regular payment, escrow included. |
payment_cadence string · required | One of weekly, monthly, quarterly, annually. |
payment_day integer | null · required | Day of the month payments fall on, 1–28, or -1 for the month's last day. |
projection | Null when the terms cannot be projected (not amortizing, or no payment or rate). |
rate_type string · required | fixed or variable. |
schedule | Every remaining period until payoff, capped at 600. Empty when there is no projection. |
scheduled_entry_id integer | null · required | The standing order that posts the loan's interest and payments, when it has one. |
source string · required | manual, inferred (from the bank) or assistant. |
status string · required | suggested (inferred from the bank, awaiting a verdict), confirmed, closed or dismissed. Only confirmed loans post and count in plans. |
term_months integer | null · required |
curl -X PATCH "https://api.lumaledger.app/v1/loans/{loan_id}" \
-H "Authorization: Bearer $LUMALEDGER_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'/v1/loans/{loan_id}/statusConfirm, close or dismiss a loan
Confirm a loan found from the bank (which starts its standing order), close one that is paid off, or dismiss one that is not yours. A dismissed loan posts nothing and is no longer listed; it is kept so the next sync does not suggest it again.
Parameters
loan_id integer · path · required | |
X-Organization-Id string | null · header |
Body · LoanStatusChange
escrow_account_id integer | null | |
escrow_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
payment_account_id integer | null | |
payment_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
status string · required | One of confirmed, dismissed, closed. |
Returns 200 · LoanDetail
accrual_mode string · required | amortizing: a level payment posts each period and splits into interest and principal. accrue_only: interest accrues to a payable, no payments are modelled. statement: the servicer reports the interest and the ledger never computes it. |
annual_rate string | null · required | Annual interest rate in percent, as a decimal string: "6.125". |
balance Money · required | What is owed today: the liability account's balance, positive while owed. |
day_count string · required | How a period's interest counts days: act365, act360, thirty360. |
escrow_account_id integer | null · required | The account the escrow share of a payment goes to. |
escrow_amount | The escrow share of each payment. |
id integer · required | |
interest_account_id integer | null · required | The expense account interest posts to. |
kind string · required | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer · required | The liability account that holds the balance. |
maturity_date date | null · required | |
name string · required | |
original_principal | |
origination_date date | null · required | |
payable_account_id integer | null · required | The liability accrued interest posts to (accrue_only loans). |
payment_account_id integer | null · required | The account payments leave from. |
payment_amount | The regular payment, escrow included. |
payment_cadence string · required | One of weekly, monthly, quarterly, annually. |
payment_day integer | null · required | Day of the month payments fall on, 1–28, or -1 for the month's last day. |
projection | Null when the terms cannot be projected (not amortizing, or no payment or rate). |
rate_type string · required | fixed or variable. |
schedule | Every remaining period until payoff, capped at 600. Empty when there is no projection. |
scheduled_entry_id integer | null · required | The standing order that posts the loan's interest and payments, when it has one. |
source string · required | manual, inferred (from the bank) or assistant. |
status string · required | suggested (inferred from the bank, awaiting a verdict), confirmed, closed or dismissed. Only confirmed loans post and count in plans. |
term_months integer | null · required |
curl -X POST "https://api.lumaledger.app/v1/loans/{loan_id}/status" \
-H "Authorization: Bearer $LUMALEDGER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "…"
}'/v1/loans/payoff-planPlan paying off every debt
Simulate paying off every confirmed debt month by month, two ways: avalanche (the highest rate first, cheapest in interest) and snowball (the smallest balance first). Both roll a finished debt's payment into the next one, and both are compared with the baseline of paying each debt's regular payment and nothing more. The arithmetic is monthly, so dates are to the month.
Parameters
extra string · query | Extra put towards debt each month on top of the regular payments, as a decimal string ("250.00"). At most 1000000. |
X-Organization-Id string | null · header |
Returns 200 · PayoffPlan
baseline PayoffBaseline · required | |
debts | |
extra_monthly Money · required | The extra put towards debt each month, as asked. |
skipped | |
strategies | |
total_balance Money · required | |
total_monthly_payment Money · required |
curl -X GET "https://api.lumaledger.app/v1/loans/payoff-plan" \
-H "Authorization: Bearer $LUMALEDGER_TOKEN"Objects
Loan
A debt with terms: a mortgage, auto, student or personal loan, a HELOC or a card.
Fields
accrual_mode string · required | amortizing: a level payment posts each period and splits into interest and principal. accrue_only: interest accrues to a payable, no payments are modelled. statement: the servicer reports the interest and the ledger never computes it. |
annual_rate string | null · required | Annual interest rate in percent, as a decimal string: "6.125". |
balance Money · required | What is owed today: the liability account's balance, positive while owed. |
day_count string · required | How a period's interest counts days: act365, act360, thirty360. |
escrow_account_id integer | null · required | The account the escrow share of a payment goes to. |
escrow_amount | The escrow share of each payment. |
id integer · required | |
interest_account_id integer | null · required | The expense account interest posts to. |
kind string · required | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer · required | The liability account that holds the balance. |
maturity_date date | null · required | |
name string · required | |
original_principal | |
origination_date date | null · required | |
payable_account_id integer | null · required | The liability accrued interest posts to (accrue_only loans). |
payment_account_id integer | null · required | The account payments leave from. |
payment_amount | The regular payment, escrow included. |
payment_cadence string · required | One of weekly, monthly, quarterly, annually. |
payment_day integer | null · required | Day of the month payments fall on, 1–28, or -1 for the month's last day. |
projection | Null when the terms cannot be projected (not amortizing, or no payment or rate). |
rate_type string · required | fixed or variable. |
scheduled_entry_id integer | null · required | The standing order that posts the loan's interest and payments, when it has one. |
source string · required | manual, inferred (from the bank) or assistant. |
status string · required | suggested (inferred from the bank, awaiting a verdict), confirmed, closed or dismissed. Only confirmed loans post and count in plans. |
term_months integer | null · required |
LoanCreate
A loan's terms. Which fields matter depends on accrual_mode: an
amortizing loan needs annual_rate and payment_amount; an
accrue-only one needs annual_rate and a payable_account_id.
Fields
accrual_mode string · required | One of accrue_only, amortizing, statement. |
annual_rate string | null | Annual rate in percent, as a decimal string: "6.125". 0–200. Pattern: ^\d{1,3}(\.\d{1,4})?$. |
day_count string | One of act365, act360, thirty360. Default: "act365". |
escrow_account_id integer | null | Where the escrow share goes. |
escrow_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
interest_account_id integer | null | Expense account for interest. |
kind string · required | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer · required | The liability account that holds the balance (see accounts.list). One loan per account. |
maturity_date date | null | |
name string · required | |
original_principal string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
origination_date date | null | |
payable_account_id integer | null | Liability for accrued interest (accrue_only). Must not be the loan's own account. |
payment_account_id integer | null | The account payments leave from. |
payment_amount string | null | The regular payment, escrow included. Pattern: ^\d{1,12}(\.\d{1,2})?$. |
payment_cadence string | One of weekly, monthly, quarterly, annually. Default: "monthly". |
payment_day integer | null | 1–28, or -1 for the month's last day. |
rate_type string | fixed or variable. Default: "fixed". |
term_months integer | null | 1–1200. |
LoanDetail
A loan with its full amortization table from today.
Fields
accrual_mode string · required | amortizing: a level payment posts each period and splits into interest and principal. accrue_only: interest accrues to a payable, no payments are modelled. statement: the servicer reports the interest and the ledger never computes it. |
annual_rate string | null · required | Annual interest rate in percent, as a decimal string: "6.125". |
balance Money · required | What is owed today: the liability account's balance, positive while owed. |
day_count string · required | How a period's interest counts days: act365, act360, thirty360. |
escrow_account_id integer | null · required | The account the escrow share of a payment goes to. |
escrow_amount | The escrow share of each payment. |
id integer · required | |
interest_account_id integer | null · required | The expense account interest posts to. |
kind string · required | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer · required | The liability account that holds the balance. |
maturity_date date | null · required | |
name string · required | |
original_principal | |
origination_date date | null · required | |
payable_account_id integer | null · required | The liability accrued interest posts to (accrue_only loans). |
payment_account_id integer | null · required | The account payments leave from. |
payment_amount | The regular payment, escrow included. |
payment_cadence string · required | One of weekly, monthly, quarterly, annually. |
payment_day integer | null · required | Day of the month payments fall on, 1–28, or -1 for the month's last day. |
projection | Null when the terms cannot be projected (not amortizing, or no payment or rate). |
rate_type string · required | fixed or variable. |
schedule | Every remaining period until payoff, capped at 600. Empty when there is no projection. |
scheduled_entry_id integer | null · required | The standing order that posts the loan's interest and payments, when it has one. |
source string · required | manual, inferred (from the bank) or assistant. |
status string · required | suggested (inferred from the bank, awaiting a verdict), confirmed, closed or dismissed. Only confirmed loans post and count in plans. |
term_months integer | null · required |
LoanList
A page of loans, in id order. Dismissed loans are not listed.
Fields
data | |
has_more boolean · required | |
next_cursor string | null · required |
LoanPeriod
One payment period of the amortization table.
LoanProjection
What the terms imply from today's balance. Recomputed on every read.
Fields
never_pays_off boolean · required | The payment does not cover the interest, so the balance would grow forever. |
payoff_date date | null · required | The period the balance reaches zero. Null when it never does. |
periods_remaining integer · required | |
total_interest Money · required | Interest still to pay from today until payoff. |
LoanStatusChange
Confirming an inferred loan is also where the accounts the bank cannot know are supplied: where the payment leaves from and where escrow goes.
Fields
escrow_account_id integer | null | |
escrow_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
payment_account_id integer | null | |
payment_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
status string · required | One of confirmed, dismissed, closed. |
LoanUpdate
Only the fields sent change. A nullable field sent as null is cleared.
Fields
accrual_mode string | One of accrue_only, amortizing, statement. |
annual_rate string | null | Pattern: ^\d{1,3}(\.\d{1,4})?$. |
day_count string | One of act365, act360, thirty360. |
escrow_account_id integer | null | |
escrow_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
interest_account_id integer | null | |
kind string | One of mortgage, auto, student, personal, heloc, credit_card, other. |
liability_account_id integer | |
maturity_date date | null | |
name string | |
original_principal string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
origination_date date | null | |
payable_account_id integer | null | |
payment_account_id integer | null | |
payment_amount string | null | Pattern: ^\d{1,12}(\.\d{1,2})?$. |
payment_cadence string | One of weekly, monthly, quarterly, annually. |
payment_day integer | null | |
rate_type string | fixed or variable. |
term_months integer | null | 1–1200. |
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}$. |
PayoffBaseline
Each debt paid at its regular payment, with nothing extra and no freed-up payment rolled into the next: what happens with no plan.
Fields
debt_free_date date | null · required | |
months integer | null · required | |
total_interest Money · required |
PayoffDebt
Fields
annual_rate string · required | Annual interest rate in percent, as a decimal string. |
balance Money · required | |
kind string · required | |
loan_id integer · required | |
monthly_payment Money · required | What goes to this debt each month today, escrow excluded. |
name string · required | |
payment_estimated boolean · required | No payment is on file, so the usual card minimum was assumed. |
PayoffPlan
Which debt to pay first and what the order is worth, across every confirmed loan still owed.
Fields
baseline PayoffBaseline · required | |
debts | |
extra_monthly Money · required | The extra put towards debt each month, as asked. |
skipped | |
strategies | |
total_balance Money · required | |
total_monthly_payment Money · required |
PayoffSkipped
Fields
loan_id integer · required | |
name string · required | |
reason string · required | Why it was left out: no_rate (no interest rate on file). |
PayoffStep
Fields
interest Money · required | Interest paid on this debt until then. |
loan_id integer · required | |
months integer · required | |
name string · required | |
payoff_date date · required | First of the month this debt reaches zero. |
PayoffStrategy
Fields
debt_free_date date | null · required | Null when the payments never clear the interest. |
interest_saved Money · required | Against the baseline. Never negative. |
months integer | null · required | |
months_saved integer · required | |
steps | The debts in the order they are paid off. |
strategy string · required | avalanche (highest rate first) or snowball (smallest balance first). |
total_interest Money · required |