API documentation

One endpoint that matters: send a vehicle, get back a market value estimate and the realized comparable sales it was built from. Base URL https://api.residualauto.com.

Authentication

Pass your key in the X-API-Key header on every request. Keys are bound to your account, rate-limited per minute, and metered against a monthly quota. A missing or revoked key returns 401; an exhausted quota or rate limit returns 429.

Create a valuation

POST /v1/valuations

curl -s https://api.residualauto.com/v1/valuations \
  -H "X-API-Key: $RESIDUAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vin": "4T1B11HK5KU211111",
    "odometer": 78421,
    "primary_damage": "FRONT END",
    "title_group": "SALVAGE",
    "state": "TX",
    "acv_estimate": 14200,
    "repair_cost": 9800,
    "condition_grade": "RUNS AND DRIVES"
  }'

Identity: VIN or year/make/model

Every request needs enough identity to value against: either a vin (decoded server-side via the federal vPIC database to fill year, make, model, and engine specs) or explicit year + make + model. Fields you pass explicitly always win over VIN-decoded values. Requests without either return 422.

Input tiers — completeness drives accuracy

The model tolerates missing fields, but its measured error depends heavily on what you send. Every response declares which tier the request landed in (input_tier) so downstream systems can weight the estimate appropriately.

Tier	What you send	Measured median error
listing-grade	Identity + damage/title + any of: ACV or repair estimate, condition grade, auction branch	~14%
identity-only	VIN or year/make/model, little else	~50%

The practical rule: if the vehicle is or was listed at auction, copy everything visible on the listing page into the request. If you're an insurer valuing a fresh total loss, your own ACV and repair estimate are the two highest-value fields. Current tier error rates are published on the accuracy page.

Request fields

Field	Type	Notes
vin	string	11–17 chars; decoded server-side
year	int	Required if no VIN
make	string	Required if no VIN; case-insensitive
model	string	Required if no VIN
trim	string
odometer	number	Miles
primary_damage	string	e.g. FRONT END, SIDE, WATER/FLOOD
secondary_damage	string
title_group	string	e.g. CLEAN, SALVAGE, NON-REPAIRABLE
state	string	Two-letter US state
source	string	copart \| iaai if known
acv_estimate	number	Pre-loss actual cash value, USD
retail_estimate	number	Estimated retail value, USD
repair_cost	number	Estimated repair cost, USD
auction_location	string	Auction yard/branch, e.g. TX - DALLAS
condition_grade	string	e.g. RUNS AND DRIVES, STATIONARY
has_keys	bool
fuel_type, drive_type, transmission, color, engine, body_style, sale_type, insurance_value, engine_hp, displacement_l, engine_cylinders	—	Optional context; send if known

Unknown fields are rejected (422) rather than ignored, so typos fail loudly.

Response

{
  "estimate": 6425.0,          // point estimate of realized sale price, USD
  "currency": "USD",
  "interval": null,            // p10/p50/p90 once calibrated intervals ship
  "n_comparables": 40,
  "comps": [                   // closest realized sales, ranked by similarity
    {
      "year": "2019", "make": "Toyota", "model": "Camry",
      "primary_damage": "FRONT END", "title_group": "SALVAGE TITLE",
      "odometer": "81250", "sale_date": "2026-06-18",
      "realized_price": 6100.0, "similarity": 0.94
    }
  ],
  "input_tier": "listing-grade",
  "accuracy_note": "…",        // plain-language note on expected error for this tier
  "model": {
    "tag": "…", "trained_through": "2026-07-02", "version_id": "…"
  },
  "disclaimer": "…"
}

Every response is stamped with the model version that produced it, so estimates are reproducible and auditable after model updates.

Other endpoints

Endpoint	Auth	Returns
GET /v1/health	none	Service status and model tag
GET /v1/model	key	Model tag, training cutoff, version id

Errors

Status	Meaning
401	Missing, invalid, or revoked API key
422	Insufficient identity (need VIN or year+make+model), or unknown field
429	Per-minute rate limit or monthly quota exceeded
502	VIN decode unavailable — retry, or send year/make/model directly

Terms of use

Responses are market value estimates from a statistical model, not appraisals, and every response carries the full disclaimer. Estimates and comps are licensed for your internal valuation workflows and client deliverables; bulk redistribution or resale of the underlying comp data requires a separate agreement.