Mortgage affordability API
The largest loan and home price an income supports, from housing and debt-to-income ratios you set (28% and 36% by default).
POST https://api.curatedapi.com/v1/calc/finance/mortgage-affordability
- Version 1
- MCP tool
calc_finance_mortgage_affordability - Try it in the browser
Lenders compare monthly payments with gross monthly income. This calculator takes two limits: the share of income that may go to housing costs, and the share that may go to all debt payments together. It finds the largest housing payment that meets both, takes off property tax, insurance and fees, and turns what is left into the loan that a level monthly payment repays at the given rate and term. The ratios are inputs because lenders and loan programmes use different ones.
Formula
housing = min(income × housing ratio, income × debt ratio − debts); P&I = housing − taxes, insurance and fees; loan = P&I × ((1+r)^n − 1) ÷ (r × (1+r)^n), r = annual rate ÷ 12
- 28% and 36% are a common rule of thumb, not a law. Set the ratios your lender or loan programme uses.
- This is arithmetic on the figures given, not a credit decision or advice.
- Amounts are plain numbers in any single currency; no currency conversion is done.
Inputs
Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).
| Input | Type | Description |
|---|---|---|
gross_monthly_income required |
decimal (string) | Income per month before tax. Allowed: > 0 and <= 1000000000000000. Unit: currency. |
monthly_debt_payments |
decimal (string) default 0 |
Other debt payments per month: car loans, student loans, credit card minimums. Allowed: >= 0 and <= 1000000000000000. Unit: currency. |
annual_rate_percent required |
decimal (string) | The mortgage's annual interest rate. Allowed: >= 0 and <= 100. Unit: percent. |
term_years required |
integer | The mortgage term in years. Allowed: >= 1 and <= 50. |
down_payment |
decimal (string) default 0 |
Cash paid towards the price. Allowed: >= 0 and <= 1000000000000000. Unit: currency. |
monthly_taxes_insurance_and_fees |
decimal (string) default 0 |
Property tax, home insurance, mortgage insurance and association fees per month. Allowed: >= 0 and <= 1000000000000000. Unit: currency. |
housing_ratio_percent |
decimal (string) default 28 |
The most of gross income that may go to housing costs (the front-end ratio). Allowed: > 0 and <= 100. Unit: percent. |
debt_ratio_percent |
decimal (string) default 36 |
The most of gross income that may go to housing costs and other debts together (the back-end or debt-to-income ratio). Allowed: > 0 and <= 100. Unit: percent. |
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 |
|---|---|---|
max_monthly_housing_payment | decimal (string) | The largest monthly housing cost that meets both ratios. Unit: currency. |
max_principal_and_interest | decimal (string) | What is left for the loan payment after taxes, insurance and fees. Unit: currency. |
max_loan_amount | decimal (string) | The loan that payment repays. Unit: currency. |
max_home_price | decimal (string) | The loan plus the down payment. Unit: currency. |
limited_by | string | Which ratio set the limit: housing_ratio or debt_ratio. |
Examples
6,000 a month, 500 of other debts, 6.5% over 30 years
curl https://api.curatedapi.com/v1/calc/finance/mortgage-affordability \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"gross_monthly_income": "6000",
"monthly_debt_payments": "500",
"annual_rate_percent": "6.5",
"term_years": 30,
"down_payment": "40000",
"monthly_taxes_insurance_and_fees": "450"
}'
{
"calculator": "finance/mortgage-affordability@1",
"result": {
"max_monthly_housing_payment": "1660.00",
"max_principal_and_interest": "1210.00",
"max_loan_amount": "191435.09",
"max_home_price": "231435.09",
"limited_by": "debt_ratio"
},
"exactness": {
"max_monthly_housing_payment": "exact",
"max_principal_and_interest": "exact",
"max_loan_amount": "rounded",
"max_home_price": "rounded"
},
"precision": {
"rounding": "half_even",
"decimals": 2
},
"inputs": {
"gross_monthly_income": "6000",
"monthly_debt_payments": "500",
"annual_rate_percent": "6.5",
"term_years": 30,
"down_payment": "40000",
"monthly_taxes_insurance_and_fees": "450",
"housing_ratio_percent": "28",
"debt_ratio_percent": "36"
},
"formula": "housing = min(income × housing ratio, income × debt ratio − debts); P&I = housing − taxes, insurance and fees; loan = P&I × ((1+r)^n − 1) ÷ (r × (1+r)^n), r = annual rate ÷ 12",
"references": [
{
"title": "Consumer Financial Protection Bureau: What is a debt-to-income ratio?",
"url": "https://www.consumerfinance.gov/ask-cfpb/what-is-a-debt-to-income-ratio-en-1791/"
}
],
"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.