Data & Analytics

Rank lenders by total cost of a loan (fees + lifetime interest)

Apples-to-apples multi-lender ranking by TOTAL cost of a loan (upfront origination/lender fees + interest paid over the holding period), not just the headline rate. Composes the decision engine's APR-ranked credit-union offers and layers fee + lifetime-interest math on top, re-ranking lenders by total cost over the holding period and flagging when the lowest-rate lender is not the cheapest overall. This route is the single source of truth; the MCP compare_total_cost tool and the consumer app call it.

Billing: each call is metered against your API key usage. Authentication required: Pass your API key in the X-API-Key header.

post/v1/total-cost

Request

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

Request body

product_type'mortgage' | 'auto_loan' | 'personal_loan' | 'heloc' | 'student_loan' required

Loan or deposit product this applies to.

statestring required

Two-letter US state code.

amountnumber required

Loan principal (> 0)

intent'purchase' | 'refinance'

Defaults to purchase

term_monthsinteger

Defaults per product (mortgage 360)

credit_scoreinteger

Borrower FICO score used to scope which offers apply.

down_payment_percentnumber

Down payment as a percentage of purchase price.

holding_period_monthsinteger

Horizon for the total-cost comparison. Defaults to term_months; clamped to <= term_months.

max_lendersinteger

Cap on ranked rows. Default 10, hard cap 25.

Example request

{
  "state": "CA",
  "amount": 400000,
  "term_months": 360,
  "credit_score": 720,
  "down_payment_percent": 20,
  "holding_period_months": 84
}

Response

Lenders re-ranked by total cost over the holding period.

product_typestring

Loan or deposit product this applies to.

statestring

Two-letter US state code.

intentstring

What the borrower is trying to do — for example purchase or refinance.

amountnumber

Loan amount in US dollars.

term_monthsinteger nullable

Loan term in months.

holding_period_monthsinteger nullable

How long the borrower is assumed to hold the loan. Defaults to the term and is clamped to it; null when no term is known.

ranked_bystring

What the ranking is ordered on. Always total_cost on this route — that is the point of it.

rerankedboolean

True when the cheapest lender is not the headline rate leader — that is, when the fee and interest math changed the winner.

notestring

Plain-language explanation of what this result means.

disclosuresstring[]

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

next_actionsstring[]

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

Example response

{
  "ranked_by": "total_cost",
  "ranked": [
    {
      "rateapi_url": "https://rateapi.dev/credit-unions/ca/schoolsfirst-federal-credit-union"
    }
  ]
}

Changes

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