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
- Version 1
- MCP tool
calc_finance_mortgage - Try it in the browser
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).
| Input | Type | Description |
|---|---|---|
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.
| Result | Type | Description |
|---|---|---|
loan_amount | decimal (string) | Price minus down payment. Unit: currency. |
down_payment | decimal (string) | Down payment amount. Unit: currency. |
loan_to_value_percent | decimal (string) | Loan amount as a percent of the price. Unit: percent. |
monthly_principal_and_interest | decimal (string) | Monthly principal and interest payment. Unit: currency. |
monthly_property_tax | decimal (string) | Annual property tax ÷ 12. Unit: currency. |
monthly_home_insurance | decimal (string) | Annual insurance ÷ 12. Unit: currency. |
monthly_hoa | decimal (string) | Monthly HOA dues. Unit: currency. |
monthly_pmi | decimal (string) | Monthly PMI while it applies. Unit: currency. |
total_monthly_payment | decimal (string) | Total of the monthly items above (first month). Unit: currency. |
pmi_months | integer | Number of months PMI is charged. |
total_pmi | decimal (string) | Total PMI paid. Unit: currency. |
total_interest | decimal (string) | Total interest over the life of the loan. Unit: currency. |
total_principal_and_interest | decimal (string) | Sum of all principal and interest payments. Unit: currency. |
last_principal_and_interest_payment | decimal (string) | The final payment, which clears the balance exactly. Unit: currency. |
number_of_payments | integer | Number of monthly payments. |
schedule | list of object | The amortization schedule (when include_schedule is true). |
Examples
CFPB sample loan
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
}'
{
"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
- 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
- Homeowners Protection Act of 1998 (PMI cancellation and termination), 12 U.S.C. 4902
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.