---
title: "Compare loan options side by side"
method: POST
path: "/api/v1/compare-loans"
tags: ["calculations"]
---

# Compare loan options side by side

`POST /api/v1/compare-loans`

## Request

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

Compares two to five loan scenarios and reports which is cheapest by monthly payment and which by lifetime cost, separately, because they frequently are not the same loan. Use for 15-year versus 30-year, FHA versus conventional, competing lender quotes, or with and without discount points.

## Request body

- object: Compare loan options. Reports the cheapest by monthly payment and by lifetime cost separately, because they often differ.
  - `scenarios` object[], required: Two to five loan scenarios to compare side by side.
    - `label` string, required: Name for this option, for example "30-year fixed".
    - `input` object, required: Full monthly housing cost: principal, interest, taxes, insurance, PMI and HOA.
      - `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.

## 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)