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

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

InputTypeDescription
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.

ResultTypeDescription
max_monthly_housing_paymentdecimal (string)The largest monthly housing cost that meets both ratios. Unit: currency.
max_principal_and_interestdecimal (string)What is left for the loan payment after taxes, insurance and fees. Unit: currency.
max_loan_amountdecimal (string)The loan that payment repays. Unit: currency.
max_home_pricedecimal (string)The loan plus the down payment. Unit: currency.
limited_bystringWhich ratio set the limit: housing_ratio or debt_ratio.

Examples

6,000 a month, 500 of other debts, 6.5% over 30 years

Requestcurl
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"
  }'
200 OKResponse
{
  "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.