---
title: "Collateral Score"
method: POST
path: "/v1/vehicle/collateral-score"
tags: ["Collateral Score"]
---

# Collateral Score

`POST /v1/vehicle/collateral-score`

## Request

- Base URL: `https://api.carsxe.com`
- URL: `https://api.carsxe.com/v1/vehicle/collateral-score`
- Auth: API key in query parameter `key`
- TypeScript: <https://skmtc.dev/carsxe/apis/carsxe-api/docs/v1/vehicle/collateral-score/post.ts> (a function with typed inputs; its response is checked against the schema)

Single-call collateral risk assessment for lenders. Returns market values adjusted for mileage and the ZIP's region, a depreciation forecast at 12/24/36/48 months (and at loan maturity), the vehicle's depreciation percentile within its vehicle class, title brand and odometer flags, open stop-sale/do-not-drive recalls, and a risk tier (A–D) with a suggested maximum LTV. Every value traces to a source: anything the score could not see is `null` and listed in `data_gaps`, and forecasts past the depreciation curve's data are `null`, never extrapolated. Available on request; contact sales to enable it. The example VIN `3TMKB5FNXRM012539` is free and never counted.

## Request body

- CollateralScoreRequest
  - `vin` string, required
  - `mileage` integer, required: Current odometer reading in miles.
  - `zip` string, required: US ZIP; its state sets the regional value adjustment.
  - `loan_term_months` integer: Adds `depreciation_forecast.at_loan_maturity`.

## Response `200`

Vehicle scored.

- object
  - `success` true
  - `input` CollateralScoreRequest
    - `vin` string, required
    - `mileage` integer, required: Current odometer reading in miles.
    - `zip` string, required: US ZIP; its state sets the regional value adjustment.
    - `loan_term_months` integer: Adds `depreciation_forecast.at_loan_maturity`.
  - `timestamp` string, date-time
  - `vin` string
  - `vehicle` object
    - `year` integer, nullable
    - `make` string, nullable
    - `model` string, nullable
    - `trim` string, nullable
  - `current_values` object: Average-condition market values, adjusted for mileage and region.
    - `retail` integer, nullable
    - `wholesale` integer, nullable
    - `trade_in` integer, nullable
    - `msrp` integer, nullable
    - `confidence` 'high' | 'medium' | 'low'
    - `publish_date` string, nullable
  - `depreciation_forecast` object: `current_values.retail` projected by the ratio between today's and the horizon's points on a depreciation curve rebuilt monthly from market values (median retail ÷ MSRP by vehicle age).
    - `12_month` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
      - `months` integer
      - `projected_value` integer
      - `depreciation_pct` number
    - `24_month` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
      - `months` integer
      - `projected_value` integer
      - `depreciation_pct` number
    - `36_month` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
      - `months` integer
      - `projected_value` integer
      - `depreciation_pct` number
    - `48_month` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
      - `months` integer
      - `projected_value` integer
      - `depreciation_pct` number
    - `at_loan_maturity` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
      - `months` integer
      - `projected_value` integer
      - `depreciation_pct` number
    - `base_value` 'retail'
    - `curve_source` 'model' | 'segment' | 'null', nullable: `model` is this make/model's own curve; `segment` is its vehicle class average.
    - `curve_key` string, nullable
    - `curve_min_sample_size` integer, nullable: Fewest valuations behind any curve point the projections used.
    - `curve_refreshed_at` string, date-time, nullable
  - `depreciation_velocity` object
    - `percentile_vs_segment` integer, nullable: Share of models in the segment that lose value more slowly; lower is better.
    - `segment` string, nullable
    - `segment_name` string, nullable
    - `annual_depreciation_pct` number, nullable
    - `peer_count` integer
    - `interpretation` string, nullable
  - `risk_flags` object: `null` means the source was unavailable, not that the vehicle is clean.
    - `salvage_title` boolean, nullable
    - `flood_damage` boolean, nullable
    - `lemon_law_buyback` boolean, nullable
    - `odometer_anomaly` boolean, nullable
    - `other_title_brands` string[], nullable
    - `total_loss_reported` boolean, nullable
    - `open_recalls_high_severity` integer, nullable
    - `accident_count` integer, nullable: Always `null` for now; accident history is not yet available.
    - `total_flags` integer
  - `lending_recommendation` object
    - `risk_tier` 'A' | 'B' | 'C' | 'D'
    - `suggested_max_ltv` 120 | 110 | 95 | 80
    - `manual_review_recommended` boolean
    - `reasons` string[]
    - `rationale` string
    - `confidence` 'high' | 'medium' | 'low'
  - `data_gaps` string[]

## Other responses

- `400`: Invalid VIN, mileage, ZIP, or loan term.
- `401`: Missing API key, unknown/disabled API key, or inactive account.
- `404`: No market value exists for this VIN, so it cannot be scored, or the API is not enabled for this account.
- `429`: API usage limit exceeded for the current billing period.
- `500`: Internal server error.
- `502`: The market value or title history lookup failed. When the body has `retryable: true` (and the response a `Retry-After` header), the same request may succeed later. Without the field, retrying the same request will not help. A recalls outage never fails the score: it is reported in `data_gaps` instead.
- `503`: The collateral score is temporarily switched off for all accounts. Nothing was charged; retry later.
- `504`: The market value or title history provider timed out. Retry after `Retry-After`.

## Changes

- **2026-10-23** `ac8fcb028169`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/carsxe/apis/carsxe-api/changes/v1/vehicle/collateral-score/post.md)

---

[API](https://skmtc.dev/carsxe/apis/carsxe-api.md) - [All operations](https://skmtc.dev/carsxe/apis/carsxe-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carsxe/apis/carsxe-api/revisions/ed8f6c024239?raw)