The dealer inventoryAPI, keyed four ways
One rooftop's live listings, paged like a search. Key the request by website host, by dealer_site_id, by dealer_id, or by entity_dealer_id for a whole shared campus. The catalog tracks 67,091 dealer websites carrying 19,349,581 listings. Every one of these routes is a scan call at 10 millicredits.
How do I pull one dealership's live inventory?
The listings API exposes a dealership's active inventory on four routes, all under /v1_2/listings/dealers/ and all returning the same paged data plus meta envelope that search returns. Key by website host - the netloc, for example exampleford.com - or by the stable dealer_site_id that every listing row carries. Key by dealer_id for the dealership running a site, or by entity_dealer_id to sweep every website of one business, which is how co-located stores sharing a lot come back together. The choice of key changes the answer: inventory by dealer_id serves that dealership's own storefront only, and cars from a store it shares a lot with do not appear there. Paging, sort and cursors behave exactly as they do on search, and each call is one scan charge of 10 millicredits.
Four keys, three different scopes
The host route and the site route each serve one website. The dealer route serves the dealership that runs a website. The entity route serves every site of one business as a single paged result set, and it accepts any member dealership's dealer_id, not only the one we picked as the business id. Rows still carry their own dealer_id throughout, so you can tell which store on a campus listed each car.
An unknown key 404s here, unlike on search
Pass a site id or dealer id we do not know to an inventory route and you get 404 dealer_not_found, because these routes need a real target. The same unknown value used as a search filter returns an empty result set with a 200 instead. A rooftop we do know that has nothing listed today is also a 200 with an empty data array - a cleared-out lot, not a missing dealer. Branch on the status code, not the row count.
The site id is stable; the domain is not
dealer_site_id is an opaque 32-character string for one website, and the same website always yields the same id, so it is safe to persist indefinitely. Identity follows the domain, though: a dealer moving to a new domain is a new dealer_site_id, and continuity across that rename is dealer_id's job. One domain fronting several physical rooftops is a single site with a single id - separate those rooftops using the listing's own city and postal code.
Priced like a search, not like a record
Every inventory route is scan class: 10 millicredits per started 100 rows returned, with page_size going up to 1000. A 350-car rooftop is four charges - roughly four hundredths of a credit to sweep in full - whether you take it as four pages of 100 or one page of 350. Widening the page changes the number of round trips, not the bill. Walk the larger rooftops with meta.next_cursor rather than numbered pages, holding the sort steady the whole way.
Compliance & sourcing
Listings are third-party inventory as of the most recent refresh. They can lag a dealership's own system and carry no warranty as to the availability, price, or saleability of any individual vehicle - which is why a rooftop sweep is sound input for market analysis and a poor substitute for calling the store. Your API key is issued to you alone: you are responsible for keeping it secret, for every call made with it, and for staying inside your rate limits.
Frequently asked questions
How do I get a single dealership's live inventory?
Call one of the dealers inventory routes with whichever key you hold. If you know the website, use the host route with its domain or the site route with its dealer_site_id. If you hold our dealer_id for the rooftop, use the dealer route. All of them return the same paged shape as search - a data array of listing rows plus a meta object with page, page_size, total and next_cursor - and each is one scan charge.
What is the difference between dealer_id and entity_dealer_id?
dealer_id identifies the dealership running one specific website, so it is what you attribute a car to. entity_dealer_id identifies the business a storefront belongs to, because dealerships sharing a physical address are one business even when each runs its own site. That makes it many-to-one: it is the right key for rolling a campus up and the wrong key for a per-rooftop count, which would count that campus once per store. Inventory by dealer id serves one storefront; inventory by entity id serves the whole campus in one paged result set.
Why is a dealership's inventory coming back empty?
An empty data array with a 200 means we know the dealership and it has nothing listed today. A 404 dealer_not_found means the key itself is unknown to us. Those are deliberately different answers. Worth knowing too: a website we cannot tie to any dealership still yields a usable dealer_site_id, so the host and site routes keep working in cases where the dealer route has nothing to key on.
How current is a dealer's inventory in the API?
The catalog swaps to the day's fresh US and Canada inventory each morning, and every row carries first_seen and last_seen dates so you can separate new listings from ones that have been sitting. The data reflects third-party inventory as of that refresh and may lag a dealership's own systems, so treat it as advertised inventory rather than confirmation that one specific car is still for sale.
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.