The VIN lookupendpoint for live listings
One path takes both keys. GET /v1_2/listings/vehicles/ plus a listing id or a VIN resolves the key as an id first and then as a VIN, and hands back the vehicle on its own with no wrapper. 94.3% of the 19,349,581 listings in the catalog carried a VIN when we last measured, on August 30, 2026. A lookup is 1 millicredit.
How do I look up a vehicle listing by VIN?
Put the VIN in the final path segment of GET /v1_2/listings/vehicles/ - the same route you would use for a listing id. The service tries the key as an id first, then as a VIN, and answers with the listing object directly: no data or meta wrapper, and only the fields that carry a value. A key matching neither is 404 vehicle_not_found. Because one car is often advertised on several websites at once, a VIN key also returns two arrays that a listing id never does: co_listings, the same dealership's other sites carrying that VIN, and other_claimants, every other dealer advertising it. Both are capped at 20 rows each. This is the cheapest metered call on the API at 1 millicredit, so 1 credit buys 1,000 of them. For the heavier record - notes, options, features, packages, seller phones and emails, photo_urls, history_urls - append /full to the same path, which bills at the vdp class of 5 millicredits.
One route, two kinds of key
The key is resolved as an id first and only then as a VIN, so an id wins a tie. Hand it a listing id and you get exactly that listing back. Hand it a VIN and you get a representative listing plus the claim arrays. Nothing else changes between the two - same path, same shape, same 1 millicredit.
The claim arrays use the opposite null convention
Listing cards are sparse: a field with no value is left out entirely, so an unresolved dealer_id is an absent key rather than a null. The entries inside co_listings and other_claimants are the reverse - a fixed shape with explicit nulls, so you can index every field unconditionally. Getting these two conventions the wrong way round is the most common integration bug on this endpoint.
VIN coverage is high, and we publish the exact figure
94.3% of the 19,349,581 listings in the catalog carry a decodable VIN as of August 30, 2026. The rest are reachable by listing id and through search, just not by VIN. We give the measured rate rather than a rounded-up one, because a lookup returning 404 vehicle_not_found for a car genuinely sitting on a lot is a fill-rate question, not a defect.
1 millicredit for the card, 5 for the full record
The card lookup is keyed class - 1 millicredit, so 1,000 lookups to a credit. Appending /full returns the card plus the hydrated extras and bills at the vdp class of 5 millicredits, or 200 full records to a credit. Only fetch /full when you need the arrays; the card already carries year, make, model, trim, price, odometer, location and the selling website.
Frequently asked questions
Is there a separate VIN lookup endpoint?
No, and there does not need to be one. GET /v1_2/listings/vehicles/ takes either key in the same path segment, resolving it as a listing id first and then as a VIN. That means one code path in your client whether you are re-reading a listing you already stored or arriving with a VIN from somewhere else, and one price - 1 millicredit - for both.
What happens when several dealers list the same VIN?
A VIN lookup returns one representative listing as the body plus two arrays. co_listings holds the rest of the winning claim: the same dealership's other websites advertising that VIN. other_claimants holds every other dealer advertising it, each entry naming its own website and its own asking price. Both arrays are always present, empty when there is nothing to report, and capped at 20 rows each. A lookup by listing id never returns either one.
Does the VIN lookup decode the VIN?
It returns the live listing advertising that VIN, not a decode. You get the listing's own published attributes - year, make_name, model_name, trim_name, sale_price, odometer, body_style, fuel_name, certified, new_vehicle, the selling website, and the first_seen and last_seen dates. This is a listings API: it tells you what is being advertised and by whom. It is not a VIN-decoding service.
How much does a VIN lookup cost?
1 millicredit per call, the smallest charge on the listings API, which is 1,000 lookups per credit. The full record at the same path plus /full costs 5 millicredits, or 200 records per credit. There is no subscription and no minimum, and a 404 vehicle_not_found - like any 4xx or 5xx - is refunded rather than billed.
More vehicle listings
Try Hermes Data for $0.99
Self-serve access to the automotive data your business runs on. The $0.99 trial gives you 20 credits to spend across Contacts, Dealers, and Dealer Groups. Then auto-upgrade to Starter ($99/mo) — or cancel any time.
Contacts, Dealers, and Dealer Groups are all self-serve on one credit wallet — spend your trial credits on any of them. Vehicle Listings is live too, on its own API subscription (separate from the credit wallet). Explore Listings.