---
title: "Build an amortization schedule"
method: POST
path: "/api/v1/calculate-amortization"
tags: ["calculations"]
---

# Build an amortization schedule

`POST /api/v1/calculate-amortization`

## Request

- Base URL: `https://www.usmortgagecalc.com`
- URL: `https://www.usmortgagecalc.com/api/v1/calculate-amortization`
- Auth: none declared

Payment-by-payment breakdown of how a loan is repaid, showing the split between principal and interest and the falling balance. Use granularity 'monthly' for the first years in detail, 'yearly' for a whole-term overview. Also reports how much sooner extra principal pays the loan off.

## Request body

- object: Amortization schedule showing how each payment splits between principal and interest.
  - `homePrice` number, required: Purchase price of the home in US dollars.
  - `downPaymentPercent` number: Down payment as a percentage of the purchase price, 0 to 100. Not a dollar amount.
  - `annualInterestRatePercent` number: Annual nominal interest rate as a percentage, for example 6.5 for 6.5%.
  - `loanTermYears` integer: Loan term in years. Most US mortgages are 15 or 30.
  - `loanType` 'conventional' | 'fha' | 'va' | 'usda': Loan programme. Affects mortgage insurance and upfront fees.
  - `annualInsurance` number: Annual homeowners insurance premium in US dollars.
  - `monthlyHoa` number: Monthly homeowners association dues in US dollars.
  - `monthlyExtraPrincipal` number: Additional principal paid each month. Shortens the loan rather than lowering the payment.
  - `state` string: Full US state name, for example "Texas". Used to look up the average property tax rate. Either this or propertyTaxRatePercent is required.
  - `propertyTaxRatePercent` number: Annual property tax as a percentage of home value. Omit and pass `state` instead to use that state's average.
  - `granularity` 'yearly' | 'monthly': Yearly returns one row per year; monthly returns one row per payment, up to 600 rows.

## Response `200`

Calculation result.

- object
  - `data` object: The calculation result.
  - `meta` object
    - `operation` string
    - `computedAt` string, date-time

## Other responses

- `400`: Input failed validation. The message names the offending field.
- `429`: Rate limit exceeded. Retry after the interval in Retry-After.

---

[API](https://skmtc.dev/usmortgagecalc/apis/us-mortgage-calculator-api.md) · [All operations](https://skmtc.dev/usmortgagecalc/apis/us-mortgage-calculator-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usmortgagecalc/apis/us-mortgage-calculator-api/revisions/4439848058a8?raw)