Vehicle entity

Read inventory records and replace ordered vehicle photo URLs through the dealership API.

#Endpoints

Inventory records owned by the dealership. Vehicle responses include public listing URLs, pricing, status, photos, incentives, equipment, tags, and core specs.

GET/v1/vehicles

GET/v1/vehicles/{id}

Auth

Send the dealership API key in the x-api-key header.

Detail IDs

Detail routes use the UUID returned by the corresponding list endpoint.

Dates

Date fields and date filters use ISO 8601 timestamps.

#Filters and Limits

List endpoints share the same pagination envelope. Query booleans use true or false.

Parameter	Type	Required	Notes
limit	number	No	Number of records to return. Defaults to `100`. Maximum is `500`.
offset	number	No	Number of records to skip. Defaults to `0`.
search	string	No	Optional text search. Searchable fields are listed on each entity.
createdAfter	datetime	No	Return records created at or after an ISO 8601 timestamp.
createdBefore	datetime	No	Return records created at or before an ISO 8601 timestamp.
updatedAfter	datetime	No	Return records updated at or after an ISO 8601 timestamp.
updatedBefore	datetime	No	Return records updated at or before an ISO 8601 timestamp.
condition	VehicleCondition	No	`NEWUSED`
status	VehicleStatus	No	`IN_STOCKIN_TRANSIT`
sold	boolean	No	Use `true` or `false`.
displayOnSite	boolean	No	Use `true` or `false`.
vin	string	No	Exact VIN match.
stockNumber	string	No	Exact stock number match.

Entity filters

Common list filters plus condition, status, sold, displayOnSite, vin, stockNumber, and search.

Search fields

vin, stockNumber, make, model, and trim.

Exact filters

vin and stockNumber are exact-match filters.

Default sort

updatedAt descending, then id descending.

VehicleCondition

NEWUSED

VehicleStatus

IN_STOCKIN_TRANSIT

JSON

{
  "data": [],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 0
  }
}

#Response

Field	Type	Nullable	Notes
id	uuid	No	Vehicle ID.
dealershipId	uuid	No	Dealership that owns the vehicle.
title	string	No	Generated display title.
vin	string	No	Vehicle identification number.
stockNumber	string	Yes	Dealer stock number.
slug	string	No	Vehicle detail slug.
year	number	No	Model year.
make	string	No	Make.
model	string	No	Model.
trim	string	No	Trim.
condition	VehicleCondition	No	`NEWUSED`
status	VehicleStatus	No	`IN_STOCKIN_TRANSIT`
sold	boolean	No	Whether the vehicle is sold.
displayOnSite	boolean	No	Whether the vehicle should display on the public site.
odometer	number	No	Mileage/odometer value.
msrp	number	Yes	MSRP.
price	number	Yes	Advertised price.
dealerDiscountedPrice	number	Yes	Dealer discounted price.
photos	url[]	No	Ordered photo URL list.
video	url	Yes	Vehicle video URL.
tags	string[]	No	Vehicle tags.
features	string[]	No	Equipment/features.
incentives	json[]	No	Applied incentives.
mobility	object	No	Mobility conversion attributes.
specs	object	No	Dimensions, towing, payload, and horsepower specs.
publicUrl	url	Yes	Public vehicle detail URL.
syncedAt	datetime	Yes	Last inventory sync timestamp.
createdAt	datetime	No	Creation timestamp.
updatedAt	datetime	No	Last update timestamp.

Identity

id, dealershipId, title, vin, stockNumber, slug, year, make, model, and trim.

Status

condition, status, sold, cpo, reserved, commercial, special, displayOnSite, and removedFromInventoryAt.

Pricing

msrp, price, dealerDiscountedPrice, totalIncentives, and totalDiscount.

Media

Ordered photos URL array, nullable video, and nullable publicUrl.

Specs

Transmission, doors, drivetrain, body, fuel, MPG, engine, color, odometer, mobility attributes, dimensions, towing, payload, and horsepower fields.

Dates

syncedAt, createdAt, and updatedAt ISO 8601 timestamps.

#Example Request

Shell

curl "https://api.driverseat.io/v1/vehicles?condition=NEW&sold=false&displayOnSite=true" \
  -H "x-api-key: sk-driverseat-..."

#Example Response

JSON

{
  "data": [
    {
      "id": "vehicle-id",
      "title": "2023 Ford F-150 XLT",
      "vin": "1FTFW1E50PFA00000",
      "stockNumber": "F1000",
      "year": 2023,
      "make": "Ford",
      "model": "F-150",
      "trim": "XLT",
      "condition": "NEW",
      "status": "IN_STOCK",
      "sold": false,
      "photos": [
        "https://example.com/photo-1.jpg"
      ],
      "publicUrl": "https://example-dealer.com/new/2023-ford-f-150-xlt"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}

#Photos

Use the photo endpoint to replace the ordered list of photo URLs for a vehicle that already exists in the dealership inventory.

POST/v1/update-photos

Auth

Dealership API key in x-api-key.

Content-Type

application/json

Request body

vinstringrequired

17-character vehicle identification number.

dealershipIdstringrequired

Dealership UUID. Must match the dealership the API key belongs to.

photosstring[]required

Absolute URL strings, in display order. This fully replaces the vehicle's existing photo list.

Example request

Shell

curl -X POST https://api.driverseat.io/v1/update-photos \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-driverseat-..." \
  -d '{
    "dealershipId": "00000000-0000-0000-0000-000000000000",
    "vin": "1FTFW1E50PFA00000",
    "photos": [
      "https://example.com/photo-1.jpg",
      "https://example.com/photo-2.jpg"
    ]
  }'

Example response

JSON

{
  "success": true,
  "vehicle": {
    "id": "vehicle-id",
    "vin": "1FTFW1E50PFA00000",
    "make": "Ford",
    "model": "F-150",
    "year": 2023,
    "photos": [
      "https://example.com/photo-1.jpg",
      "https://example.com/photo-2.jpg"
    ]
  }
}

Behavior

The photos array is a full replacement. Omitted previous URLs are removed.
Photo order is preserved exactly as submitted.
Send an empty array to clear the vehicle's photos.
The endpoint stores URLs; it does not upload image files.
After a successful update, the public vehicle page is revalidated in the background.

Photo URLs should be publicly reachable and suitable for display on vehicle detail pages.

Photo errors

400

Invalid request body. Common causes: a VIN that is not 17 characters, a non-UUID dealershipId, or an invalid photo URL.

401

The API key is missing, invalid, or does not belong to the submitted dealershipId.

404

No vehicle was found for the submitted VIN within the authorized dealership.

#Errors

400

Invalid query parameter or resource ID. Common causes include a limit above 500, an invalid UUID, an invalid datetime, or an unsupported enum value.

401

The API key is missing, invalid, or revoked.

404

The requested vehicle does not exist or does not belong to the dealership authorized by the API key.