Data & Analytics

Lender competitive position (where do MY rates rank)

Lender-facing 'is my offer competitive' check. Input your published note rate (and optional APR) for a state + mortgage product and get a market percentile (share of live offers strictly below your APR), bps vs the state median, and a leading / competitive / overpriced verdict. Mortgage-only (30-year or 15-year fixed). Distinct from /v1/rate-sanity-check, which validates an inbound borrower quote. This route is the single source of truth; the MCP check_competitive_position tool and the consumer app call it.

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

post/v1/competitive-position

Request

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

Request body

statestring required

2-letter US state code.

product'30yr_fixed' | '15yr_fixed' required

Mortgage product you publish.

ratenumber required

Your published note rate as a percentage.

aprnumber

Your published APR. Optional — falls back to rate.

Example request

{
  "state": "CA",
  "product": "30yr_fixed",
  "rate": 6.49,
  "apr": 6.62
}

Response

Market position for the supplied offer.

statestring

Two-letter US state code.

product'30yr_fixed' | '15yr_fixed'

Mortgage product the offer was positioned against.

percentileinteger

Share of live offers strictly below your APR (lower = more competitive).

bps_vs_medianinteger nullable

(your_apr - median) in bps; negative = below median = cheaper.

verdict'leading' | 'competitive' | 'overpriced' | 'below_floor' | 'unknown'

Where the offer sits: leading beats most of the market, competitive sits in the normal range, overpriced sits well above the median, below_floor falls under what this product plausibly prices at, unknown when there was no market to compare against.

notestring

Plain-language explanation of what this result means.

Changes

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