> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosnap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Vehicles
> The vehicle object — every field, every type
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](/api-reference/endpoints/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](/get-started/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
```json theme={null}
{
"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](/concepts/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](/concepts/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` | 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](/concepts/provider-coverage) for per-provider field details.
## How to get vehicle data
Use the [Fetch Inventory](/api-reference/endpoints/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](/concepts/premium-data-packages). Packages are optional add-ons, disabled by default, and enabled per-dealership through your account manager.
## Related concepts
* [Dealerships](/concepts/dealerships) — the dealership object and how resolution works
* [Pricing Breakdown](/concepts/pricing-breakdown) — the structured pricing object
* [Premium Data Packages](/concepts/premium-data-packages) — optional paid add-ons for deeper per-VIN data