curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Mortgage API

Monthly mortgage payment including property tax, insurance, HOA dues and PMI, with an exact amortization schedule.

POST https://api.curatedapi.com/v1/calc/finance/mortgage

Splits the monthly housing payment into principal and interest, property tax, home insurance, HOA dues and private mortgage insurance (PMI). Principal and interest use the same exact, lender-style schedule as the loan EMI calculator. PMI applies when the loan is more than 80% of the price and stops once the scheduled balance reaches 78% of the original price, the automatic termination point in the US Homeowners Protection Act.

Formula

P&I = L·r·(1+r)^n / ((1+r)^n − 1), L = price − down payment, r = rate ÷ 1200, n = years × 12; total = P&I + tax/12 + insurance/12 + HOA + PMI
  • Amounts are plain numbers in any single currency; no currency conversion is done.
  • PMI is estimated as a fixed yearly percent of the original loan amount. Real PMI pricing depends on the lender and credit score, and borrowers can usually ask to cancel it at 80% loan-to-value; this calculator uses the automatic 78% point.
  • Tax and insurance are assumed constant; in reality they change over time.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
home_price required decimal (string) Purchase price of the home. Allowed: > 0 and <= 1000000000000000. Unit: currency.
down_payment decimal (string) Down payment as an amount. Give this or down_payment_percent. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
down_payment_percent decimal (string) Down payment as a percent of the price. Give this or down_payment. Allowed: >= 0 and <= 100. Unit: percent.
annual_rate_percent required decimal (string) Nominal annual interest rate in percent. Allowed: >= 0 and <= 100. Unit: percent.
term_years required integer Length of the mortgage in years. Allowed: >= 1 and <= 50.
annual_property_tax decimal (string)
default 0
Property tax per year. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
annual_home_insurance decimal (string)
default 0
Home insurance premium per year. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
monthly_hoa decimal (string)
default 0
Homeowners association dues per month. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
pmi_annual_rate_percent decimal (string)
default 0
PMI premium per year as a percent of the original loan amount (often 0.3 to 1.5). Only applied when the loan is above 80% of the price. Allowed: >= 0 and <= 10. Unit: percent.
include_schedule boolean
default False
Also return the month-by-month schedule.
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
loan_amountdecimal (string)Price minus down payment. Unit: currency.
down_paymentdecimal (string)Down payment amount. Unit: currency.
loan_to_value_percentdecimal (string)Loan amount as a percent of the price. Unit: percent.
monthly_principal_and_interestdecimal (string)Monthly principal and interest payment. Unit: currency.
monthly_property_taxdecimal (string)Annual property tax ÷ 12. Unit: currency.
monthly_home_insurancedecimal (string)Annual insurance ÷ 12. Unit: currency.
monthly_hoadecimal (string)Monthly HOA dues. Unit: currency.
monthly_pmidecimal (string)Monthly PMI while it applies. Unit: currency.
total_monthly_paymentdecimal (string)Total of the monthly items above (first month). Unit: currency.
pmi_monthsintegerNumber of months PMI is charged.
total_pmidecimal (string)Total PMI paid. Unit: currency.
total_interestdecimal (string)Total interest over the life of the loan. Unit: currency.
total_principal_and_interestdecimal (string)Sum of all principal and interest payments. Unit: currency.
last_principal_and_interest_paymentdecimal (string)The final payment, which clears the balance exactly. Unit: currency.
number_of_paymentsintegerNumber of monthly payments.
schedulelist of objectThe amortization schedule (when include_schedule is true).

Examples

CFPB sample loan

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/mortgage \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "home_price": "180000",
    "down_payment": "18000",
    "annual_rate_percent": "3.875",
    "term_years": 30
  }'
200 OKResponse
{
  "calculator": "finance/mortgage@1",
  "result": {
    "loan_amount": "162000.00",
    "down_payment": "18000.00",
    "loan_to_value_percent": "90.00",
    "monthly_principal_and_interest": "761.78",
    "monthly_property_tax": "0.00",
    "monthly_home_insurance": "0.00",
    "monthly_hoa": "0.00",
    "monthly_pmi": "0.00",
    "total_monthly_payment": "761.78",
    "pmi_months": 0,
    "total_pmi": "0.00",
    "total_interest": "112243.67",
    "total_principal_and_interest": "274243.67",
    "last_principal_and_interest_payment": "764.65",
    "number_of_payments": 360
  },
  "exactness": {
    "loan_amount": "exact",
    "down_payment": "exact",
    "loan_to_value_percent": "exact",
    "monthly_principal_and_interest": "exact",
    "monthly_property_tax": "exact",
    "monthly_home_insurance": "exact",
    "monthly_hoa": "exact",
    "monthly_pmi": "exact",
    "total_monthly_payment": "exact",
    "total_pmi": "exact",
    "total_interest": "exact",
    "total_principal_and_interest": "exact",
    "last_principal_and_interest_payment": "exact"
  },
  "precision": {
    "rounding": "half_even",
    "decimals": 2
  },
  "inputs": {
    "home_price": "180000",
    "down_payment": "18000",
    "annual_rate_percent": "3.875",
    "term_years": 30,
    "annual_property_tax": "0",
    "annual_home_insurance": "0",
    "monthly_hoa": "0",
    "pmi_annual_rate_percent": "0",
    "include_schedule": false
  },
  "formula": "P&I = L·r·(1+r)^n / ((1+r)^n − 1), L = price − down payment, r = rate ÷ 1200, n = years × 12; total = P&I + tax/12 + insurance/12 + HOA + PMI",
  "references": [
    {
      "title": "CFPB Regulation Z Appendix H, form H-24(B) sample Loan Estimate: $162,000 at 3.875% for 30 years, principal and interest $761.78 per month",
      "url": "https://www.consumerfinance.gov/rules-policy/regulations/1026/h/"
    },
    {
      "title": "Homeowners Protection Act of 1998 (PMI cancellation and termination), 12 U.S.C. 4902",
      "url": "https://www.law.cornell.edu/uscode/text/12/4902"
    }
  ],
  "warnings": []
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.