Developers
API reference

Loans

get/v1/loans

List loans

loans.listread tokenidempotent

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
array of Loan · required
has_more
boolean · required
next_cursor
string | null · required
Example
curl -X GET "https://api.lumaledger.app/v1/loans" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"
post/v1/loans

Create a loan

loans.createwrite tokenidempotent

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
Money | null · required
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
Money | null · required
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
Money | null · required
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
LoanProjection | null · required
Null when the terms cannot be projected (not amortizing, or no payment or rate).
rate_type
string · required
fixed or variable.
schedule
array of LoanPeriod · required
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
Example
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": "…"
  }'
delete/v1/loans/{loan_id}

Delete a loan

loans.deletewrite tokendestructiveidempotent

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.

Example
curl -X DELETE "https://api.lumaledger.app/v1/loans/{loan_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"
get/v1/loans/{loan_id}

Get a loan

loans.getread tokenidempotent

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
Money | null · required
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
Money | null · required
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
Money | null · required
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
LoanProjection | null · required
Null when the terms cannot be projected (not amortizing, or no payment or rate).
rate_type
string · required
fixed or variable.
schedule
array of LoanPeriod · required
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
Example
curl -X GET "https://api.lumaledger.app/v1/loans/{loan_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"
patch/v1/loans/{loan_id}

Update a loan

loans.updatewrite tokenidempotent

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
Money | null · required
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
Money | null · required
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
Money | null · required
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
LoanProjection | null · required
Null when the terms cannot be projected (not amortizing, or no payment or rate).
rate_type
string · required
fixed or variable.
schedule
array of LoanPeriod · required
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
Example
curl -X PATCH "https://api.lumaledger.app/v1/loans/{loan_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/loans/{loan_id}/status

Confirm, close or dismiss a loan

loans.set_statuswrite tokenidempotent

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
Money | null · required
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
Money | null · required
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
Money | null · required
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
LoanProjection | null · required
Null when the terms cannot be projected (not amortizing, or no payment or rate).
rate_type
string · required
fixed or variable.
schedule
array of LoanPeriod · required
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
Example
curl -X POST "https://api.lumaledger.app/v1/loans/{loan_id}/status" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "…"
  }'
get/v1/loans/payoff-plan

Plan paying off every debt

loans.payoff_planread tokenidempotent

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
array of PayoffDebt · required
extra_monthly
Money · required
The extra put towards debt each month, as asked.
skipped
array of PayoffSkipped · required
strategies
array of PayoffStrategy · required
total_balance
Money · required
total_monthly_payment
Money · required
Example
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
Money | null · required
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
Money | null · required
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
Money | null · required
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
LoanProjection | null · required
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
Money | null · required
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
Money | null · required
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
Money | null · required
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
LoanProjection | null · required
Null when the terms cannot be projected (not amortizing, or no payment or rate).
rate_type
string · required
fixed or variable.
schedule
array of LoanPeriod · required
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
array of Loan · required
has_more
boolean · required
next_cursor
string | null · required

LoanPeriod

One payment period of the amortization table.

Fields

balance_after
Money · required
escrow
Money · required
interest
Money · required
period_end
date · required
principal
Money · required

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
array of PayoffDebt · required
extra_monthly
Money · required
The extra put towards debt each month, as asked.
skipped
array of PayoffSkipped · required
strategies
array of PayoffStrategy · required
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
array of PayoffStep · required
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