Data & Analytics

Position an external quote in the live market distribution

Takes an externally-sourced quote (rate/APR) for a product in a state and reports where it falls in the live market APR distribution: percentile, min/median/max, a classification, and a plain-language note. It can also return named lower-rate alternatives and product-matched rates from credit unions with NCUA-reported branches near an optional ZIP. ZIP proximity is source-labelled and does not claim road distance. Also flags quotes below the per-product APR floor as likely data errors or teaser rates.

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

post/v1/rate-sanity-check

Request

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

Request body

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

The market to score the quote against. Use mortgage_arm for an adjustable-rate mortgage (5/1, 5/5, 7/1, 10/1, ...) — ARM intro rates run structurally below fixed rates, so scoring an ARM against the fixed market makes an ordinary quote look market-leading. All initial fixed periods share ONE mortgage_arm bucket. Use mortgage for fixed-rate mortgages and set term_months to pick 15- vs 30-year.

statestring required

2-letter US state code

ratenumber required

The quoted nominal rate (percent).

aprnumber

Optional quoted APR (percent). Falls back to rate when omitted.

feesnumber

Optional quoted fees in dollars (surfaced in the note, not folded into APR).

amountnumber

Optional loan amount in dollars.

term_monthsinteger

Optional loan term in months. For mortgage, this selects the comparison market: under 300 months scores against the 15-year distribution, 300+ against the 30-year. Ignored for mortgage_arm, which is a single bucket.

vehicle_conditionstring

For auto_loan only: 'used'/'certified_pre_owned'/'cpo' selects the used benchmark bucket; otherwise the new bucket is used.

zipstring

Optional borrower ZIP. Used for membership context and, with include_nearby_offers, NCUA-reported branch proximity.

include_better_offersboolean

When true, include a bounded list of statewide offers currently beating the quote.

include_nearby_offersboolean

When true and zip is supplied, include product-matched rates from credit unions ranked by estimated distance to the closest NCUA-reported branch.

Example request

{
  "product_type": "auto_loan",
  "state": "CA",
  "rate": 6.49,
  "apr": 6.75,
  "fees": 395,
  "amount": 35000,
  "term_months": 72,
  "vehicle_condition": "new",
  "zip": "95814"
}

Response

Quote positioned against the live market distribution.

product_typestring

Loan or deposit product this applies to.

statestring

Two-letter US state code.

percentileinteger

Percentile of the market the quote's APR sits at (0=best/lowest).

classification'market_leading' | 'plausible' | 'suspicious_low' | 'overpriced' | 'unknown'

Verdict on the quote: market_leading beats most of the market, plausible sits in the normal range, suspicious_low falls below the product floor and is likely a teaser or a misread, overpriced sits well above the median, unknown when there was no market to compare against.

below_product_floorboolean

True when the quoted APR falls below the lowest rate this product plausibly prices at, which usually means the figure is a promotional teaser or was misread.

product_floornumber

The lowest APR this product plausibly prices at, as an annual percentage.

notestring

Plain-language explanation of what this result means.

Changes

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