Vehicles

The vehicle is the primary object in AutosnapAI. It represents a single real-world vehicle in a dealer’s inventory, uniquely identified by its VIN + dealership.

v1.0 schema lock. The set of keys documented on this page is the locked v1.0 contract for vehicles[i] in the Fetch Inventory response. We will never remove a documented key, never rename a documented key, and never change a documented type without bumping to v2 (see Versioning). New fields may be added additively; your client must tolerate unknown keys.

Stable schema — every documented key is always present. Every vehicle object returned by the API contains every documented field. When a value is unavailable for that vehicle, the field is populated with null rather than omitted. Your client should expect every key to exist on every record and check for null to determine availability.

Object shape

{
  "id": "d8a1c0e2-7b42-4f9a-b0e1-5a1f0c2d9b73",
  "vin": "5GAEVBKSXTJ122446",
  "year": 2026,
  "make": "Buick",
  "model": "Enclave",
  "series": "Sport Touring",
  "heading": "2026 Buick Enclave Sport Touring",
  "stocknum": "22260048",
  "condition": "New",
  "certified": false,
  "body": "SUV",
  "transmission": "Automatic",
  "drivetrain_desc": "All Wheel Drive",
  "engine": "2.5L Turbo engine",
  "engine_cyl_count": 4,
  "engine_displacement": "2.5",
  "fuel": "Gasoline Fuel",
  "door_count": 4,
  "odometer": 5,
  "city_mpg": 18,
  "hwy_mpg": 24,
  "exterior_color": "Iridescent White Tricoat",
  "interior_color": "Ebony",
  "base_ext_color": "White",
  "base_int_color": "Black",
  "price": 42479,
  "msrp": 56495,
  "internet_price": null,
  "list_price": null,
  "invoice_price": null,
  "book_value": null,
  "discount_amount": 14815,
  "final_price": 42479,
  "total_discounts": 14815,
  "total_fees": 799,
  "price_components": {
    "components": [
      { "type": "msrp", "label": "MSRP", "amount": 56495, "category": "starting" },
      { "type": "dealer_incentive", "label": "Dealer Discount", "amount": 7065, "category": "discount" },
      { "type": "incentive_consumer_cash", "label": "Bonus Cash", "amount": 7750, "category": "discount" },
      { "type": "dealer_fee", "label": "Documentation Fee", "amount": 799, "category": "fee" },
      { "type": "net_price_with_dealer_fees", "label": "Final Price", "amount": 42479, "category": "final" }
    ],
    "starting_price": 56495,
    "final_price": 42479,
    "total_discounts": 14815,
    "total_fees": 799
  },
  "age_days": 42,
  "features": ["AWD", "Heated Seats", "Apple CarPlay"],
  "description": "This 2026 Buick Enclave Sport Touring is...",
  "photo_url_list": [
    { "url": "https://vehicle-images.carscommerce.inc/...", "index": 0 },
    { "url": "https://vehicle-images.carscommerce.inc/...", "index": 1 }
  ],
  "vdp_link": "https://www.carlblackroswell.com/inventory/...",
  "in_transit": false,
  "dealership_active": true,
  "first_seen_at": "2026-02-25T14:32:19Z",
  "scraped_date": "2026-04-08",
  "created_at": "2026-02-25T14:32:19Z",
  "updated_at": "2026-04-08T09:15:44Z",
  "last_seen": "2026-04-08T09:15:44Z",
  "inventory_date": "2026-02-25"
}

Core identifiers

Field	Type	Description
`id`	`uuid`	Stable internal identifier. Safe to store.
`vin`	`string(17)`	Vehicle Identification Number
`year`	`integer`	Model year
`make`	`string`	Manufacturer (e.g. “Buick”, “GMC”, “Ford”)
`model`	`string`	Model name (e.g. “Enclave”, “Yukon”, “F-150”)
`heading`	`string`	Full listing title (e.g. “2026 Buick Enclave Sport Touring”)
`stocknum`	`string \| null`	The dealer’s internal stock number. `null` when the dealer’s feed doesn’t publish one.

VIN uniqueness is per-dealer, not global. Inventory is scoped to each dealership. The same VIN may legitimately appear as separate records at multiple dealerships when:

A dealer group shares used-inventory across multiple rooftop websites (both sites publicly list the same physical vehicle, typically with identical stocknum and price)
A vehicle has recently transferred between dealers and the prior dealer’s site has not yet removed the listing

Use the composite key (dealership_id, vin) for uniqueness. If you need to deduplicate across dealers, prefer the record with the most recent last_seen timestamp. The internal id (UUID) is always globally unique and safe to store as a primary key on your side.

Condition and certification

Field	Type	Description
`condition`	`enum`	`"New"` or `"Used"`. Certified Pre-Owned vehicles have condition `"Used"` with `certified: true`.
`certified`	`boolean`	`true` for OEM Certified Pre-Owned vehicles

Specifications

Field	Type	Description
`body`	`string \| null`	Body style (e.g. “SUV”, “Sedan”, “Trucks”)
`transmission`	`string \| null`	Transmission description
`series`	`string \| null`	Trim level / series name
`engine`	`string \| null`	Engine description
`engine_cyl_count`	`integer \| null`	Number of cylinders. `null` when the dealer’s feed doesn’t publish one (zero values are converted to `null`).
`engine_displacement`	`string \| null`	Engine displacement in liters
`fuel`	`string \| null`	Fuel type (e.g. “Gasoline Fuel”, “Diesel Fuel”, “Electric”)
`drivetrain_desc`	`string \| null`	Drivetrain (e.g. “FWD”, “4WD”, “All Wheel Drive”)
`door_count`	`integer`	Number of doors. `0` when the dealer’s feed doesn’t publish a value (treat `0` as “unknown” rather than literal zero doors).
`odometer`	`integer`	Mileage reading. `0` for new vehicles or when the dealer’s feed doesn’t publish a value.
`city_mpg`	`integer \| null`	EPA city fuel economy in miles per gallon
`hwy_mpg`	`integer \| null`	EPA highway fuel economy in miles per gallon

Pricing fields

Field	Type	Description
`price`	`integer \| null`	The dealer’s asking price. `null` when the dealer has not yet published pricing (e.g., future-model-year allocations, “call for price” listings).
`msrp`	`integer \| null`	Manufacturer’s Suggested Retail Price. `null` for used vehicles without a captured MSRP, or for new vehicles not yet priced by the dealer.
`internet_price`	`integer \| null`	Internet/online price when different from the asking price. `null` when not available.
`list_price`	`integer \| null`	List price if provided by the dealer. `null` when not available.
`invoice_price`	`integer \| null`	Invoice price if available. `null` when not available.
`book_value`	`integer \| null`	Book value if available. `null` when not available.
`discount_amount`	`integer \| null`	Total discount off MSRP. `null` when not available.
`final_price`	`integer \| null`	Bottom-line price after all discounts and fees. `null` when no pricing breakdown is available. See Pricing Breakdown.
`total_discounts`	`integer \| null`	Sum of all discount/incentive lines in the pricing breakdown. `null` when not available.
`total_fees`	`integer \| null`	Sum of all dealer fee lines in the pricing breakdown. `null` when not available.
`price_components`	`object \| null`	Full structured pricing breakdown. See Pricing Breakdown. `null` when no breakdown is available.

The API converts zero values to null for these fields: msrp, price, internet_price, list_price, invoice_price, book_value, discount_amount, final_price, total_discounts, total_fees, city_mpg, hwy_mpg, age_days, and engine_cyl_count.

price_components and photo_url_list are returned as native JSON objects/arrays, not as JSON strings. You can access them directly without parsing (e.g. vehicle.price_components.final_price in JavaScript or vehicle["price_components"]["final_price"] in Python).

Colors

Field	Type	Description
`exterior_color`	`string \| null`	Dealer-reported exterior color (e.g. “Iridescent White Tricoat”)
`interior_color`	`string \| null`	Dealer-reported interior color
`base_ext_color`	`string \| null`	Normalized exterior color (e.g. “White”)
`base_int_color`	`string \| null`	Normalized interior color (e.g. “Black”)

Dates and lifecycle

Field	Type	Description
`first_seen_at`	`timestamp`	When AutosnapAI first recorded this vehicle
`scraped_date`	`date`	Date of the most recent scrape that included this vehicle
`created_at`	`timestamp`	When the vehicle record was created
`updated_at`	`timestamp \| null`	When the vehicle record was last updated. `null` if never updated.
`age_days`	`integer \| null`	Days on lot, computed from first seen date. `null` when the first-seen date is unavailable (zero values are converted to `null`).
`inventory_date`	`string \| null`	Date vehicle was added to dealer inventory (YYYY-MM-DD)
`last_seen`	`string \| null`	ISO timestamp of when vehicle was last seen in a scrape
`in_transit`	`boolean`	`true` if the vehicle is not yet physically on the lot
`dealership_active`	`boolean`	`false` if the vehicle has been removed from active inventory

Media and features

Field	Type	Description
`photo_url_list`	`array`	Ordered array of photo objects, each with `url` (string) and `index` (integer). First item (index `0`) is the primary photo. May be an empty array.
`features`	`array<string>`	Feature labels extracted from the listing (e.g. “Apple CarPlay”, “Heated Seats”). May be an empty array.
`vdp_link`	`string \| null`	URL to the dealer’s Vehicle Detail Page
`description`	`string \| null`	The dealer’s free-text description

Field availability varies by dealership website provider. Not all fields are populated for every vehicle. Fields that are not available from a given provider are returned as null or 0.

Field availability

Field availability varies per provider, per dealer, and per VIN. Plan for nulls on every field except id, vin, year, make, model, and condition. See Provider Coverage for per-provider field details.

How to get vehicle data

Use the Fetch Inventory endpoint to retrieve paginated vehicle records for any active dealership.

Deeper per-VIN data

The base vehicle object captures the inventory fields every dealership publishes. For richer per-VIN data — third-party history records, dealer-provided service documentation, warranty paperwork, and more — see Premium Data Packages. Packages are optional add-ons, disabled by default, and enabled per-dealership through your account manager.

Dealerships — the dealership object and how resolution works
Pricing Breakdown — the structured pricing object
Premium Data Packages — optional paid add-ons for deeper per-VIN data

Get Started

Concepts

Guides

Support

Object shape

Core identifiers

Condition and certification

Specifications

Pricing fields

Colors

Dates and lifecycle

Media and features

Field availability

How to get vehicle data

Deeper per-VIN data

​Object shape

​Core identifiers

​Condition and certification

​Specifications

​Pricing fields

​Colors

​Dates and lifecycle

​Media and features

​Field availability

​How to get vehicle data

​Deeper per-VIN data

​Related concepts

Object shape

Core identifiers

Condition and certification

Specifications

Pricing fields

Colors

Dates and lifecycle

Media and features

Field availability

How to get vehicle data

Deeper per-VIN data

Related concepts