---
title: "Decompose why each lender ranked where it did"
method: POST
path: "/v1/explain-ranking"
tags: ["Data & Analytics"]
---

# Decompose why each lender ranked where it did

`POST /v1/explain-ranking`

## Request

- Base URL: `https://api.rateapi.dev`
- URL: `https://api.rateapi.dev/v1/explain-ranking`
- Auth: API key in header `X-API-Key`

Runs the same decision scenario as `/v1/decisions` and decomposes WHY each top lender ranked where it did: per-offer cost breakdown (rate/APR/fees/payment/lifetime interest), the scoring signals, and how much each offer beats the next-ranked one by. Accepts the same request body as `/v1/decisions`. This route is the single source of truth; the MCP `explain_ranking` tool calls it.

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

## Request body

- object
  - `decision_type` 'financing', required: Which decision to explain. This route explains financing decisions.
  - `context` object, required: Request context including geo.state. Same shape as `/v1/decisions`.
  - `borrower` object: Optional borrower attributes (e.g. credit_score). Same shape as `/v1/decisions`.
  - `product_request` object, required: Product request (product_type, intent, amount, term_months, details). Same shape as `/v1/decisions`.
  - `preferences` object: Optional preferences. `max_providers` (1-5) caps how many ranked offers are decomposed.

## Response `200`

Ranking decomposition for the top qualifying offers.

- object
  - `request_id` string: Identifier of the decision that was explained.
  - `product_type` string: Loan or deposit product this applies to.
  - `offers` object[]: The ranked offers, each decomposed into why it placed where it did.
    - `rank` integer: Position in the ranking, 1 being best.
    - `lender` string: Name of the credit union offering this rate.
    - `cost_breakdown` object: The components the weighted score was computed from.
      - `rate` number: Note rate as an annual percentage, excluding fees.
      - `apr` number: Annual percentage rate, which includes fees and is the figure offers are ranked on.
      - `points` number: Discount points priced into the rate.
      - `fees` number: Fees priced into this offer, in US dollars.
      - `monthly_payment` number: Monthly principal-and-interest payment in US dollars.
      - `lifetime_interest` number: Total interest paid over the full term, in US dollars.
    - `signals` object[]: The factors that moved this offer up or down the ranking.
    - `beats_next_by` object, nullable: How far this offer beats the one placed immediately below it, or null for the last offer.
      - `apr` number: Annual percentage rate, which includes fees and is the figure offers are ranked on.
      - `monthly_payment` number: Monthly principal-and-interest payment in US dollars.
      - `lifetime_interest` number: Total interest paid over the full term, in US dollars.
  - `summary` string: How the ranking was computed and what separated the winner, in plain language.

## Other responses

- `400`: The request was malformed — a missing required field, an unparseable body, or a parameter outside its allowed range. The `error` field names what was wrong; retrying the identical request will fail identically.
- `401`: No API key, or a key that is unknown or disabled. Send it in the `X-API-Key` header. Free keys are issued instantly by POST /keys with an email address. The response carries `WWW-Authenticate` pointing at this host's protected-resource metadata, and the `RateLimit-*` headers describing the Free-tier budget a key issued now would carry (scope `anonymous`) — a rejected request spends none of it, so `Remaining` equals `Limit`.
- `429`: Quota exhausted for the current window. `Retry-After` gives the seconds to wait; `upgradeInfo` explains how to lift the cap. Retrying before the reset will fail again and still counts as a request.

---

[API](https://skmtc.dev/rateapi/apis/rate-api.md) · [All operations](https://skmtc.dev/rateapi/apis/rate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rateapi/apis/rate-api/revisions/06a6db76995f?raw)