Data & Analytics

Amortization / payoff & extra-payment schedule

Builds a year-by-year (or month-by-month) amortization schedule for a loan: total lifetime interest, the principal/interest split per period, and a 'what if I pay $X extra/month' payoff accelerator showing months saved and interest saved. When no rate is supplied, the current best market rate for the state is resolved from real credit-union offers via the decision engine. The amortization math lives here as the single source of truth; the MCP build_amortization_schedule tool and the consumer app call this route.

Authentication required: Pass your API key in the Authorization: Bearer <key> header.

post/v1/amortization

Request

  • Base URL: https://api.rateapi.dev
  • URL: https://api.rateapi.dev/v1/amortization
  • Auth: API key in header X-API-Key

Request body

loan_amountnumber required

Loan principal in dollars (must be > 0).

term_monthsinteger required

Loan term in months, e.g. 360 or 180 (must be > 0, cap 600).

ratenumber

Annual interest rate as a percent (e.g. 6.5). If omitted, the market rate is resolved from real credit-union offers via the decision engine.

product_type'mortgage' | 'auto_loan' | 'heloc' | 'personal_loan' | 'student_loan'

Loan product; required only when rate is omitted. Default mortgage.

statestring

2-letter US state code; required only when rate is omitted (for market-rate lookup).

credit_scoreinteger

Optional borrower credit score used to qualify the market offer.

extra_monthly_paymentnumber

Optional extra principal paid each month (>= 0). Drives the payoff-acceleration analysis.

extra_one_time_paymentnumber

Optional one-time extra principal payment (>= 0).

schedule_granularity'year' | 'month'

Schedule row granularity. Default year.

Example request

{
  "loan_amount": 400000,
  "term_months": 360,
  "rate": 6.5,
  "extra_monthly_payment": 200
}

Response

Amortization schedule with baseline totals and (when extra payments are supplied) a payoff-acceleration comparison. When the rate must be resolved from the market but no offer qualifies, rate/baseline/monthly_payment are null and a reason is returned.

loan_amountnumber

Loan amount in US dollars.

ratenumber nullable

Note rate as an annual percentage, excluding fees.

rate_source'provided' | 'market' | 'fallback'

Where the rate used in this calculation came from: provided if the caller supplied it, market if it was taken from live offers, fallback if neither was available and a default was used.

market_lenderstring nullable

Credit union whose rate was used when the rate came from the market, or null when the caller supplied the rate.

term_monthsinteger

Loan term in months.

monthly_paymentnumber nullable

Monthly principal-and-interest payment in US dollars.

reasonstring

Why no schedule could be produced — present only when the response is empty because no rate was supplied and no qualifying market offer was found.

assumed_defaultsobject

Values filled in where the caller supplied none, so the result is reproducible.

next_actionsobject[]

Other endpoints or tools that are the natural next step from this result.

disclosuresstring[]

Statements that must be shown to a consumer alongside this result.

Changes

No recorded changes to this operation across all 1 revision of this API.