Data & Analytics

Rate-lock / float-down timing decision

Lock-window-aware lock-vs-float-down recommendation for a deal already in the pipeline. Given a known lock-expiration date, the currently locked rate, and the float-down cost, returns a defensible hold-lock vs exercise-float-down call a loan officer can document — combining recent market movement (1w/2w/4w window) with payment + break-even math on this loan. Builds on the same recent-movement signal as /v1/buy-timing but framed around the lock window/expiration. A documentable sensitivity scenario, NOT a rate forecast. This route is the single source of truth; the MCP assess_rate_lock tool and the consumer app call it.

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

post/v1/rate-lock

Request

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

Request body

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

Use mortgage_arm for an adjustable-rate mortgage (5/1, 5/5, 7/1, 10/1, ...). ARMs are a separate market from fixed-rate mortgages: an ARM's introductory rate sits structurally below a comparable fixed rate, so a blended list would rank every ARM on top and present it as cheaper — true only until it resets. All initial fixed periods share one mortgage_arm bucket. Within mortgage, term_months selects 15- vs 30-year; it has no meaning for mortgage_arm.

statestring required

2-letter US state code

loan_amountnumber required

Loan amount in dollars — drives payment + break-even math

term_monthsinteger

Loan term in months. Defaults to 360.

locked_ratenumber required

The rate already locked, in percent.

lock_expiration_datestring required

ISO date (YYYY-MM-DD) the lock expires.

float_down_costnumber

Dollar cost to exercise the float-down. Defaults to 0.

float_down_ratenumber

Optional explicit floated rate (percent). If absent, the best live market rate is used.

float_down_bpsnumber

Optional improvement in bps if float_down_rate is omitted and no live offer is available.

closing_costsnumber

Optional closing costs in dollars (cost framing). Defaults to 0.

since'1w' | '2w' | '4w'

Movement window. Defaults to 4w.

Example request

{
  "product_type": "mortgage",
  "state": "CA",
  "loan_amount": 400000,
  "term_months": 360,
  "locked_rate": 6.75,
  "lock_expiration_date": "2026-07-15",
  "float_down_cost": 500,
  "float_down_rate": 6.5,
  "float_down_bps": 25,
  "since": "4w"
}

Response

Lock-vs-float assessment. Degrades gracefully: when the lock is expired the recommendation is extend_or_relock; when rate history is thin, movement fields are null, recommendation is insufficient_data, confidence is low, and a note is included.

product_typestring

Loan or deposit product this applies to.

statestring

Two-letter US state code.

windowstring

How far back the rate movement was measured, as the since value used.

recommendation'exercise_float_down' | 'hold_lock' | 'let_lock_ride' | 'extend_or_relock' | 'insufficient_data'

What to do with the lock.

confidence'high' | 'medium' | 'low'

How much rate history backed the recommendation.

rationalestring

The reasoning behind the recommendation, in plain language.

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.

Changes

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