DealScore
Guide

Score a deal by VIN

To score a used car deal by VIN, send score_deal the 17-character VIN, the asking price, and the mileage, and DealScore decodes the car through NHTSA vPIC and grades the price against live US dealer listing comps. ZIP is optional if you want a local refine.

What you need

  • VIN: 17 characters, no I/O/Q. Found on the dash, door jamb, or listing photos.
  • Asking price: seller's current ask in USD.
  • Mileage: current odometer.
  • ZIP: optional. Use it only to narrow comps to a local market. The default score is national.

That's it. Year/make/model is optional; the VIN path fills it in.

NHTSA decode (vPIC)

When a VIN is submitted, DealScore calls the NHTSA vPIC API to resolve year, make, model, and trim. We don't maintain our own VIN database.

If decode fails (invalid VIN, incomplete NHTSA record), DealScore returns an error. Have the agent retry with year, make, and model instead.

Example API request

The MCP tool takes these arguments. Scripts can POST the same payload to /api/score:

POST /api/score
{
  "vin": "1HGCM82633A004352",
  "asking_price": 16000,
  "mileage": 62000,
  "zip": "78701"
}

Response includes grade, delta_pct, expected price, comp summary, brief, and risks. Production uses live market comps; see when we return cannot_score.

VIN vs. year/make/model

Both paths hit the same scoring engine. Send the VIN when the agent has one; it reduces typos on make/model and picks up trim when NHTSA has it. Use year/make/model when only those fields are available, or if decode fails.

Test a VIN on /tryHow grades workScore with an agent

Quick answers

Do I need a ZIP code to score by VIN?
No. The default score is national. A ZIP asks for a local refine within 100 miles, and when local inventory is thin the score stays national.
What happens if the VIN does not decode?
DealScore returns an error. Retry with year, make, and model instead.
Does DealScore keep its own VIN database?
No. It calls the NHTSA vPIC API to resolve year, make, model, and trim.
Is a VIN score different from a year, make, and model score?
Both paths use the same scoring engine. A VIN avoids typos in make and model and picks up trim when NHTSA has it.
Does a VIN score count toward the Free meter?
Free includes 5 scored calls a month. Only results with coverage: scored count, and explain_grade and health are never metered.