Skip to content

Goals

Create, track, and project financial goals.


Create a financial goal with specified targets.

Parameter Type Default Description
name string required Goal name (1-200 characters)
goal_type string required Kind of financial goal being created.
importance float required Success probability target (0.01-0.99, e.g., 0.90 = 90% confidence)
target_amount_cents int null Target amount in cents (for goals with a fixed savings target)
target_date string null Target date in YYYY-MM-DD format (optional)
target_date_flexibility string null How firm the target date is.
contribution_amount_cents int null Fixed monthly contribution in cents
contribution_percentage float null Contribution as % of income (e.g., 0.15 = 15%)
contribution_schedule object null A monthly contribution that starts, stops or grows, in place of contribution_amount_cents / contribution_percentage (pass none of those with it): {“monthly_amount_cents”: int, “start_date”?: “YYYY-MM-DD”, “end_date”?: “YYYY-MM-DD”, “annual_growth_rate”?: float, “real_terms”?: bool}. Both dates are inclusive and optional. For $1,293/mo from Sep 2026 through Apr 2027: {“monthly_amount_cents”: 129300, “start_date”: “2026-09-01”, “end_date”: “2027-04-30”}. Amounts are nominal (face value) unless real_terms is true, which makes them today’s dollars, grossed up by the projection’s inflation. Unknown or mistyped fields are rejected.
months_expenses int null Number of months of expenses to save (for emergency_fund goals)
status string "active" Lifecycle status of the goal.
tax_advantaged bool false Prefer tax-advantaged accounts for this goal
notes string null Additional notes about the goal
description string null Optional longer description of the goal
target_price_level object null Price level of target_amount_cents and of every payout_schedule amount. Omit for today’s dollars (real purchasing power at creation). For future nominal dollars, such as quoted future tuition bills: {“adjustment”: “nominal”}. For a specific reference purchasing power: {“adjustment”: “real”, “reference_year”: 2026, “reference_month”: 1}.
payout_schedule list null Scheduled payouts for multi-year goals (e.g. education), each {“payout_date”: “YYYY-MM-DD”, “amount_cents”: int}. Amounts are in target_price_level’s frame (today’s dollars when it is omitted), so set target_price_level to {“adjustment”: “nominal”} for face-value future bills. For tuition, prefer the generator arguments (beneficiary_id, cost_preset or annual_cost_today_cents, …) over building rows by hand; pass one or the other, never both.
deposit_schedule list null Dated one-off deposits into the goal, such as a bonus, each {“deposit_date”: “YYYY-MM-DD”, “amount_cents”: int > 0}, sorted by date. Amounts are nominal (face value on that date), whatever target_price_level says. Deposits on one date add up. Projections ignore a deposit before today (already in the balance) and note any beyond their horizon. Don’t also enter the same money as income linked to the goal, or it counts twice.
beneficiary_id string null Generator: id of the student in state_json’s household (usually a dependent). Their date_of_birth dates the school years. Passing any generator argument generates the payout_schedule instead of taking rows; beneficiary_id, state_json and exactly one of cost_preset or annual_cost_today_cents are then required.
state_json object null Generator: the user state document, used only to look up beneficiary_id.
annual_cost_today_cents int null Generator: one school year’s full cost at today’s prices, in cents. Use it for a cost the user knows, such as their expected net cost; otherwise pass cost_preset.
cost_preset string null Generator: a named school-year cost instead of annual_cost_today_cents: ‘public_in_state’, ‘public_out_of_state’ or ‘private_nonprofit’ (four-year colleges). Each is College Board’s published cost of attendance (tuition, fees, housing and food) before aid. The response’s generated_schedule.cost_preset names the figure, its source and publication year.
start_age int null Generator: the age the student reaches by the end of the first payout’s month (default 18). The first payout is the first start_month in or after the month they turn start_age: in the year they turn start_age if born in or before start_month, otherwise the year after.
years int null Generator: number of school years to pay (default 4).
education_inflation_premium float null Generator: annual tuition growth ABOVE inflation, as a decimal (0.02 = 2%). Omit for the 2% long-run default; the response then says the default was used.
start_month int null Generator: month (1-12) each school year’s payout falls in (default 8).
precondition_goal_id string null ID of a goal that must reach precondition_threshold before this goal is funded
precondition_threshold float null Fraction (0.0-1.0) of the precondition goal that must be met first

Returns the created goal as JSON including auto-generated ID and validation results.


Calculate current progress toward a goal — today’s balance only, no projection.

Parameter Type Default Description
goal_json object required Goal as a JSON dict. Required keys: name, goal_type, importance (0.01-0.99); “emergency_fund” goals also require months_expenses. current_balance_cents is optional (defaults to 0) but should be set to the goal’s funded balance (the linked account’s balance) — the goal’s own current_balance_cents is often 0 because funding is account-derived.
state_json object null Optional full user state JSON. When its accounts include one or more accounts whose goal_id matches goal_json.id, their integer balance_cents values are summed and used as the goal’s funded balance; otherwise goal_json.current_balance_cents is used.

Returns progress percentage, remaining amount, and completion status. For a goal with payouts still ahead, progress is today’s balance divided by the plain sum of the payouts still ahead (progress_basis “remaining_payouts”); otherwise it is the balance divided by the target (progress_basis “target_amount”). For whether the plan will cover the payouts, use project_goal_progress. Pass state_json to derive the funded balance from accounts linked to the goal’s id; otherwise the goal_json current_balance_cents value is used.


Project goal progress forward with compound growth.

Parameter Type Default Description
goal_json object required Goal as a JSON dict. Required keys: name, goal_type, importance (0.01-0.99); “emergency_fund” goals also require months_expenses. current_balance_cents is optional (defaults to 0) but should be set to the goal’s funded balance (the linked account’s balance). With state_json, the funded balance is resolved from accounts linked to goal_json.id; without it, passing the raw goal (often 0) projects from $0.
state_json object null Optional full user state JSON. When its accounts include one or more accounts whose goal_id matches goal_json.id, their integer balance_cents values are summed and used as the projection’s starting funded balance; otherwise goal_json.current_balance_cents is used.
annual_return_rate float 0.07 Expected annual return rate (e.g., 0.07 = 7%)
annual_volatility float 0.0 Annual return volatility (standard deviation) as a decimal (e.g., 0.15 = 15%). When > 0, the projection spreads into a percentile band (p10/p25/p50/p75/p90) so return uncertainty is visible: p10 < p50 < p90, and the median (p50) reflects volatility drag (it sits below the zero-volatility expected path). Leave 0 for a single deterministic figure.
months_ahead int null Number of months to project forward. If omitted, the projection runs to the goal’s own horizon: its last scheduled payout for a goal with payouts still ahead (or target_date if later), else its target_date (or today if it has none), so the result answers the question the goal defines rather than an arbitrary horizon. Pass a value only to override with a fixed horizon.
monthly_income_cents int 0 Caller’s monthly income in cents. Only used for goals funded by contribution_percentage (PERCENTAGE_INCOME); ignored otherwise. Leave 0 if the goal has no income-percentage contribution.
inflation float 0.0 Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, a real-terms target is inflated to the projection date’s nominal value before progress is computed, and a real-terms goal’s payout_schedule is inflated to nominal at each payout’s month, so payout_coverage is nominal. remaining_payouts_cents stays in the goal’s target_price_level frame; each block names its frame.

Returns: goal_id, goal_name, balance_source, current_balance_cents, current_balance_dollars, projection_date, months_ahead, projection_basis, annual_return_rate, and annual_volatility, and more.


Project a goal’s balance and progress as a year-by-year (or N-month) series in one call.

Parameter Type Default Description
goal_json object required Goal as a JSON dict. Required keys: name, goal_type, importance (0.01-0.99); “emergency_fund” goals also require months_expenses. current_balance_cents is optional (defaults to 0) but should be set to the goal’s funded balance (the linked account’s balance). With state_json, the funded balance is resolved from accounts linked to goal_json.id; without it, passing the raw goal (often 0) projects from $0.
state_json object null Optional full user state JSON. When its accounts include one or more accounts whose goal_id matches goal_json.id, their integer balance_cents values are summed and used as the series’ starting funded balance; otherwise goal_json.current_balance_cents is used.
annual_return_rate float 0.07 Expected annual return rate (e.g., 0.07 = 7%)
annual_volatility float 0.0 Annual return volatility (standard deviation) as a decimal. When > 0, each point spreads into a percentile band (p10/p25/p50/p75/p90); leave 0 for a single deterministic path per point.
months_ahead int null Horizon to project through. If omitted, runs to the goal’s own horizon: its last scheduled payout for a goal with payouts still ahead (or target_date if later), else its target_date (or today if it has none). The series is sampled from today to this horizon.
step_months int 12 Sampling cadence in months (default 12 = annual points). Use 1 for a monthly series. Today (month 0) and the exact horizon are always included.
monthly_income_cents int 0 Caller’s monthly income in cents. Only used for goals funded by contribution_percentage (PERCENTAGE_INCOME); ignored otherwise.
inflation float 0.0 Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, a real-terms target is inflated to each point’s nominal value before progress is computed, and a real-terms goal’s payout_schedule is inflated to nominal at each payout’s month. remaining_payouts_cents stays in the goal’s target_price_level frame, named by remaining_payouts_price_level.

Returns: goal_id, goal_name, balance_source, annual_return_rate, annual_volatility, step_months, point_count, target_amount_cents, target_amount_dollars, and series, and more.


Calculate the monthly contribution needed to reach a goal.

Parameter Type Default Description
target_amount_cents int required Target goal amount in cents
time_horizon_months int required Number of months until target date
initial_balance_cents int 0 Current savings toward goal in cents
annual_return_rate float 0.07 Expected annual return rate (e.g., 0.07 = 7%)
inflation float 0.0 Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, the target is assumed to be in today’s dollars and is inflated to the target date’s nominal value before solving.

Returns: target_amount_cents, target_amount_dollars, initial_balance_cents, initial_balance_dollars, time_horizon_months, annual_return_rate, inflation, inflation_adjusted_target_cents, inflation_adjusted_target_dollars, and cashflow_cents, and more.