API reference

Properties

get/v1/properties

List properties

properties.listread tokenidempotent

Every property in the ledger, including suggested and dismissed ones (see status), each with its mortgage and equity. Values are as last refreshed; the app refreshes Zestimates when its page is opened.

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 · PropertyList

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

Example

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

post/v1/properties

Add a property

properties.createwrite tokenidempotent

Add a property the household owns. Its value is posted to the ledger, so net worth moves with it. Send an Idempotency-Key so a retry cannot add 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 · PropertyCreate

address_line string \| null
city string \| null
country string \| null
estimated_value string \| null	What it is worth, as a decimal string. Posted to the ledger. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
label string · required	What to call it: `Lake house`.
lat string \| null	Pattern: `^-?\d{1,3}(\.\d{1,6})?$`.
lng string \| null	Pattern: `^-?\d{1,3}(\.\d{1,6})?$`.
postal_code string \| null
region string \| null
valued_at date \| null	The date the value is from. Defaults to today when a value is sent.

Returns 201 · Property

address string \| null · required	The address on one line.
address_line string \| null · required
city string \| null · required
country string \| null · required
equity Money \| null · required	Value minus the mortgage. Null unless both are known.
estimated_value Money \| null · required	What it is worth. Null when nobody has said.
excluded_from_totals boolean · required	Left out of net worth, with its mortgage. Its value is not posted to the ledger.
hidden boolean · required	Hidden from the app's lists and map; still counted.
id integer · required
label string · required
lat string \| null · required	Latitude in degrees, as a decimal string.
lng string \| null · required	Longitude in degrees, as a decimal string.
mortgage PropertyMortgage \| null · required
postal_code string \| null · required
region string \| null · required	State, province or region.
source string · required	`manual` or `inferred` (found from a mortgage).
status string · required	`suggested` (found from a mortgage, not yet reviewed), `confirmed` or `dismissed`.
value_age_days integer \| null · required	Days since `valued_at`.
value_is_stale boolean \| null · required	The value is over a year old. Null when it was never dated: not fresh, unknown.
value_source string · required	Where the value came from: `user`, `zillow` (a Zestimate), `mortgage_origination` (the loan's original principal, a stand-in) or `none`.
valued_at date \| null · required	The date the value is true for.
zillow_url string \| null · required	Zillow's page for the property. Show it beside a Zestimate, as Zillow requires.

Example

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

delete/v1/properties/{property_id}

Delete a property

properties.deletewrite tokendestructiveidempotent

Delete a property that was added by hand and take its value off the ledger. One found from a mortgage cannot be deleted (the next sync would find it again): set its status to dismissed instead.

Parameters

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

Returns 204 with no body.

Example

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

get/v1/properties/{property_id}

Get a property

properties.getread tokenidempotent

One property with its mortgage and equity.

Parameters

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

Returns 200 · Property

address string \| null · required	The address on one line.
address_line string \| null · required
city string \| null · required
country string \| null · required
equity Money \| null · required	Value minus the mortgage. Null unless both are known.
estimated_value Money \| null · required	What it is worth. Null when nobody has said.
excluded_from_totals boolean · required	Left out of net worth, with its mortgage. Its value is not posted to the ledger.
hidden boolean · required	Hidden from the app's lists and map; still counted.
id integer · required
label string · required
lat string \| null · required	Latitude in degrees, as a decimal string.
lng string \| null · required	Longitude in degrees, as a decimal string.
mortgage PropertyMortgage \| null · required
postal_code string \| null · required
region string \| null · required	State, province or region.
source string · required	`manual` or `inferred` (found from a mortgage).
status string · required	`suggested` (found from a mortgage, not yet reviewed), `confirmed` or `dismissed`.
value_age_days integer \| null · required	Days since `valued_at`.
value_is_stale boolean \| null · required	The value is over a year old. Null when it was never dated: not fresh, unknown.
value_source string · required	Where the value came from: `user`, `zillow` (a Zestimate), `mortgage_origination` (the loan's original principal, a stand-in) or `none`.
valued_at date \| null · required	The date the value is true for.
zillow_url string \| null · required	Zillow's page for the property. Show it beside a Zestimate, as Zillow requires.

Example

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

patch/v1/properties/{property_id}

Update a property

properties.updatewrite tokenidempotent

Correct a property's address, revalue it, confirm or dismiss one found from a mortgage, or hide it or leave it out of the totals. Only the fields sent change. A new value, a status change or the exclusion switch re-posts the property's value to the ledger.

Parameters

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

Body · PropertyUpdate

address_line string
city string
country string
estimated_value string	A new value. Dated today unless `valued_at` is sent with it. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
excluded_from_totals boolean	Leave it, and its mortgage, out of net worth.
hidden boolean
label string
postal_code string
region string
status string	One of `confirmed`, `dismissed`, `suggested`.
valued_at date	The date the value is from; sent alone, it re-dates the current one.

Returns 200 · Property

address string \| null · required	The address on one line.
address_line string \| null · required
city string \| null · required
country string \| null · required
equity Money \| null · required	Value minus the mortgage. Null unless both are known.
estimated_value Money \| null · required	What it is worth. Null when nobody has said.
excluded_from_totals boolean · required	Left out of net worth, with its mortgage. Its value is not posted to the ledger.
hidden boolean · required	Hidden from the app's lists and map; still counted.
id integer · required
label string · required
lat string \| null · required	Latitude in degrees, as a decimal string.
lng string \| null · required	Longitude in degrees, as a decimal string.
mortgage PropertyMortgage \| null · required
postal_code string \| null · required
region string \| null · required	State, province or region.
source string · required	`manual` or `inferred` (found from a mortgage).
status string · required	`suggested` (found from a mortgage, not yet reviewed), `confirmed` or `dismissed`.
value_age_days integer \| null · required	Days since `valued_at`.
value_is_stale boolean \| null · required	The value is over a year old. Null when it was never dated: not fresh, unknown.
value_source string · required	Where the value came from: `user`, `zillow` (a Zestimate), `mortgage_origination` (the loan's original principal, a stand-in) or `none`.
valued_at date \| null · required	The date the value is true for.
zillow_url string \| null · required	Zillow's page for the property. Show it beside a Zestimate, as Zillow requires.

Example

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

get/v1/properties/affordability

What home the household can afford

properties.affordabilityread tokenidempotent

The inputs to a home-affordability calculation, from the ledger: income, real spending, existing debt payments and cash, plus the defaults and underwriting limits the app's calculator starts from. The calculation itself (payment, ratios, verdict) is left to the client, so it can be redrawn for any price without another call.

Parameters

X-Organization-Id

string | null · header

Returns 200 · Affordability

cash_available Money · required	Cash and savings, towards a down payment.
current_housing_cost Money · required	Rent, or the running cost of the current home.
defaults AffordabilityDefaults · required
free_cash_flow Money · required	Income minus spending minus debt payments.
guidelines AffordabilityGuidelines · required
income_months integer · required	How many months `monthly_income` averages.
monthly_debt_payments Money · required	Existing loan payments, per month.
monthly_income Money · required	Averaged over the completed months of the lookback; zero with no income yet.
monthly_spending Money · required	Real monthly spending, excluding the housing a purchase would replace and debt interest (carried in `monthly_debt_payments`).

Example

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

Objects

Affordability

What the ledger says about the household's capacity to carry a home.

Fields

cash_available Money · required	Cash and savings, towards a down payment.
current_housing_cost Money · required	Rent, or the running cost of the current home.
defaults AffordabilityDefaults · required
free_cash_flow Money · required	Income minus spending minus debt payments.
guidelines AffordabilityGuidelines · required
income_months integer · required	How many months `monthly_income` averages.
monthly_debt_payments Money · required	Existing loan payments, per month.
monthly_income Money · required	Averaged over the completed months of the lookback; zero with no income yet.
monthly_spending Money · required	Real monthly spending, excluding the housing a purchase would replace and debt interest (carried in `monthly_debt_payments`).

AffordabilityDefaults

Opening values for a mortgage calculator. Percentages are decimal strings.

Fields

annual_rate_pct string · required
down_payment_pct string · required
insurance_rate_pct string · required	Annual home insurance, percent of the price.
property_tax_rate_pct string · required	Annual property tax, percent of the price.
term_year_options array of integer · required
term_years integer · required

AffordabilityGuidelines

What a housing payment is measured against. The first three are the lender's debt-to-income conventions; the cash-flow limits and reserve target are LumaLedger's.

Fields

back_end_limit_pct string · required	All debt payments as a share of gross income.
back_end_max_pct string · required	The most a lender will usually go to.
cash_flow_limit_pct string · required	Housing as a share of what is genuinely spare each month.
cash_flow_max_pct string · required
closing_cost_pct string · required
front_end_limit_pct string · required	Housing payment as a share of gross income.
pmi_annual_rate_pct string · required
pmi_ltv_threshold_pct string · required	Loan-to-value above which mortgage insurance applies.
reserve_months_target integer · required	Months of payments to keep in cash after closing.

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

Property

A home or other real estate the household owns.

Fields

address string \| null · required	The address on one line.
address_line string \| null · required
city string \| null · required
country string \| null · required
equity Money \| null · required	Value minus the mortgage. Null unless both are known.
estimated_value Money \| null · required	What it is worth. Null when nobody has said.
excluded_from_totals boolean · required	Left out of net worth, with its mortgage. Its value is not posted to the ledger.
hidden boolean · required	Hidden from the app's lists and map; still counted.
id integer · required
label string · required
lat string \| null · required	Latitude in degrees, as a decimal string.
lng string \| null · required	Longitude in degrees, as a decimal string.
mortgage PropertyMortgage \| null · required
postal_code string \| null · required
region string \| null · required	State, province or region.
source string · required	`manual` or `inferred` (found from a mortgage).
status string · required	`suggested` (found from a mortgage, not yet reviewed), `confirmed` or `dismissed`.
value_age_days integer \| null · required	Days since `valued_at`.
value_is_stale boolean \| null · required	The value is over a year old. Null when it was never dated: not fresh, unknown.
value_source string · required	Where the value came from: `user`, `zillow` (a Zestimate), `mortgage_origination` (the loan's original principal, a stand-in) or `none`.
valued_at date \| null · required	The date the value is true for.
zillow_url string \| null · required	Zillow's page for the property. Show it beside a Zestimate, as Zillow requires.

PropertyCreate

A property the household owns. Its address is geocoded unless lat and lng are sent.

Fields

address_line string \| null
city string \| null
country string \| null
estimated_value string \| null	What it is worth, as a decimal string. Posted to the ledger. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
label string · required	What to call it: `Lake house`.
lat string \| null	Pattern: `^-?\d{1,3}(\.\d{1,6})?$`.
lng string \| null	Pattern: `^-?\d{1,3}(\.\d{1,6})?$`.
postal_code string \| null
region string \| null
valued_at date \| null	The date the value is from. Defaults to today when a value is sent.

PropertyList

A page of properties, in id order.

Fields

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

PropertyMortgage

Fields

account_id integer · required	The mortgage's liability account (see `accounts.list`).
balance Money · required	What is owed on it today, positive while owed.
name string · required

PropertyUpdate

Only the fields sent change. None of them can be cleared.

Fields

address_line string
city string
country string
estimated_value string	A new value. Dated today unless `valued_at` is sent with it. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
excluded_from_totals boolean	Leave it, and its mortgage, out of net worth.
hidden boolean
label string
postal_code string
region string
status string	One of `confirmed`, `dismissed`, `suggested`.
valued_at date	The date the value is from; sent alone, it re-dates the current one.

address_line string \| null
city string \| null
country string \| null
estimated_value string \| null	What it is worth, as a decimal string. Posted to the ledger. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
label string · required	What to call it: `Lake house`.
lat string \| null	Pattern: `^-?\d{1,3}(\.\d{1,6})?$`.
lng string \| null	Pattern: `^-?\d{1,3}(\.\d{1,6})?$`.
postal_code string \| null
region string \| null
valued_at date \| null	The date the value is from. Defaults to today when a value is sent.

address_line string \| null
city string \| null
country string \| null
estimated_value string \| null	What it is worth, as a decimal string. Posted to the ledger. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
label string · required	What to call it: `Lake house`.
lat string \| null	Pattern: `^-?\d{1,3}(\.\d{1,6})?$`.
lng string \| null	Pattern: `^-?\d{1,3}(\.\d{1,6})?$`.
postal_code string \| null
region string \| null
valued_at date \| null	The date the value is from. Defaults to today when a value is sent.