Data & Analytics

Home affordability estimate from income and DTI

Borrower-facing home affordability estimate. Given gross annual income, existing monthly debts, down payment, and front-end/back-end DTI caps, computes max monthly payment, max loan amount, and max home price. When no rate is supplied the current best market rate for the state is resolved via the decision engine, with a 6.5% fallback. This route is the single source of truth; the MCP affordability tool and the consumer app call it.

Authentication required: Pass your API key in the X-API-Key header.

post/v1/affordability

Request

  • Base URL: https://api.rateapi.dev
  • URL: https://api.rateapi.dev/v1/affordability
  • Auth: API key in header X-API-Key

Request body

income_annualnumber required

Gross annual income in dollars.

monthly_debtsnumber

Existing monthly debt payments in dollars. Defaults to 0.

down_paymentnumber

Down payment in dollars. Defaults to 0.

front_end_dtinumber

Front-end DTI cap (fraction). Defaults to 0.28.

back_end_dtinumber

Back-end DTI cap (fraction). Defaults to 0.36.

term_monthsinteger

Loan term in months. Defaults to 360.

statestring

2-letter US state code. Defaults to CA.

product_typestring

Defaults to 'mortgage'.

ratenumber

Optional rate (percent). When omitted, resolved from the live market.

credit_scoreinteger

Optional credit score, used when resolving the market rate.

Example request

{
  "income_annual": 120000,
  "monthly_debts": 400,
  "down_payment": 60000,
  "front_end_dti": 0.28,
  "back_end_dti": 0.36,
  "term_months": 360,
  "state": "CA",
  "product_type": "mortgage",
  "rate": 6.5,
  "credit_score": 740
}

Response

Affordability estimate. affordable is false when existing debts exceed the back-end budget.

affordableboolean

True when the borrower can support a loan at all under the debt-to-income limits.

max_monthly_paymentstring

Largest monthly payment the borrower can support, formatted as a US dollar string.

max_loan_amountstring

Largest loan that payment supports at the rate used, formatted as a US dollar string.

max_home_pricestring

That loan plus the down payment, formatted as a US dollar string.

down_paymentstring

Down payment in US dollars.

rate_usedstring

The rate the calculation was run at, as an annual percentage.

rate_source'provided' | 'market' | 'fallback'

Where the rate used in this calculation came from: provided if the caller supplied it, market if it was taken from live offers, fallback if neither was available and a default was used.

binding_constraint'front_end_dti' | 'back_end_dti'

Which debt-to-income limit is the one actually capping the borrower: front_end_dti on housing costs alone, back_end_dti once existing debts are counted.

max_payment_valuenumber

The same figure as max_monthly_payment, as a number rather than a formatted string.

back_end_budget_valuenumber

What is left for a housing payment once existing debts are subtracted from the back-end limit, in US dollars.

assumed_defaultsobject

Values filled in where the caller supplied none, so the result is reproducible.

next_actionsobject[]

Other endpoints or tools that are the natural next step from this result.

disclosuresstring[]

Statements that must be shown to a consumer alongside this result.

notestring

Plain-language explanation of what this result means.

reasonstring

Present when affordable is false.

Changes

No recorded changes to this operation across all 1 revision of this API.