Skip to main content
POST
Fetch Website Inventory
POST /v1/inventory/fetch Retrieve paginated vehicle inventory for an active dealership. Returns vehicle records with all available fields including pricing, specifications, media, and metadata.
v1.0 schema lock. The response shape on this page is the locked v1.0 contract. We will never remove a documented field, never rename a field, and never change a field’s type without bumping to v2 (see Versioning). New fields may be added additively; your client must tolerate unknown keys. Field nullability and coverage rates are documented in Concepts: Vehicles — Field coverage SLA.

Request Body

Provide either dealership_url or dealership_id (one is required, not both). Both resolve to the same dealership server-side.

Condition Values

Example

Response

price_components and photo_url_list are returned as native JSON objects/arrays. See Concepts: Vehicles for field details and Provider Coverage: Price Breakdown for the full component schema.
Zero-to-null conversion: Fields with a value of 0 are returned as null to indicate missing data. This applies to all price fields (msrp, price, internet_price, list_price, invoice_price, book_value, discount_amount, final_price, total_discounts, total_fees), fuel economy (city_mpg, hwy_mpg), age_days, and engine_cyl_count.
Color fields: In addition to the raw exterior_color and interior_color fields, each vehicle includes base_ext_color and base_int_color — normalized base color values (e.g., “Black”, “White”, “Silver”) standardized across all providers.
Photo URL substitution: When rehosted images are available, photo_url_list contains CDN-hosted URLs instead of the original dealer website URLs. The original URLs are not returned in this case.
Per-dealer scope. The response reflects a single dealership’s public inventory. The same VIN may appear at other dealerships you have access to — most commonly when a dealer group shares used-inventory across multiple rooftop websites. See Concepts: Vehicles — Core identifiers for how to handle cross-dealer uniqueness.
Data freshness. data_age_hours (top-level, number | null) reports the number of hours since the most recent scrape pass observed any vehicle in this dealership’s active inventory, rounded to one decimal. Equivalent to now - max(vehicle.last_seen) across the whole dealership — it does not vary by page, per_page, or condition filter (whole-dealership scope, not page scope). Lower is fresher. Most dealers are scraped on a 6-hour cadence, with some on 12-hour, so a typical value is 0.5 to 12.0. Values that significantly exceed the dealer’s expected cadence indicate a delayed or failing scrape — consider a more conservative price-display strategy in that case. Returns null when the dealership has no active vehicles.

Errors

Body

application/json
api_key
string
required
dealership_url
string
required
page
integer | null
default:1
per_page
integer | null
default:50
condition
string | null

Response

Successful Response