Year Make Model - CarsXE Docs

Look up vehicle data by year, make, and model, with an optional trim hint. This is useful when a VIN is unavailable but you still need structured specs, colors, features, pricing, or trim options.

Building cascading dropdown menus instead? See YMM Options.

Decoding a diagnostic trouble code instead? See OBD Codes Decoder.

Endpoint: /v1/ymm

Parameters

Parameter	Required	Description
`year`	Yes	Vehicle model year, numeric, between 1900 and the current model year plus one
`make`	Yes	Manufacturer, for example `Toyota`, `Ford`, or `BMW`
`model`	Yes	Vehicle model, for example `Camry`, `F-150`, or `X5`
`trim`	No	Trim hint, for example `XLE` or `Sport`; fuzzy matched when possible
`allTrimOptions`	No	Pass `1` to return all trim options for the year, make, and model

Example

Look up by year, make, and model

Code

curl -G https://api.carsxe.com/v1/ymm \
  -d key=YOUR_API_KEY \
  -d year=2023 \
  -d make=Toyota \
  -d model=Camry \
  -d trim=XLE

Response

Top-level shape

{

"success": true,// always true on 200

"timestamp": "2024-03-19T12:00:00.000Z"// ISO 8601 response time

}

Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference.

All response fields are optional except success. Availability varies by vehicle, trim, and source coverage.

bestMatch

The bestMatch object contains the matched vehicle and trim data.

Name
make
Type
string
Description
Vehicle manufacturer. Example: "Toyota".
Name
model
Type
string
Description
Vehicle model. Example: "Camry".
Name
year
Type
string
Description
Vehicle model year. Example: "2023".
Name
name
Type
string
Description
Full trim and body description for the matched vehicle. Example: "XLE 4dr Sedan (3.5L 6cyl 8A)".
Name
base_msrp
Type
number
Description
Original base manufacturer's suggested retail price when available.
Name
base_invoice
Type
number
Description
Original base dealer invoice price when available.
Name
total_seating
Type
number
Description
Factory seating capacity for the matched trim.
Name
color
Type
object
Description
Available exterior and interior color options.
Name
features
Type
object
Description
Grouped feature and specification data, usually under standard.

trimOptions

When allTrimOptions=1 is passed, trimOptions returns available trims for the requested year, make, and model. Use this when users need to choose a trim before requesting the best match.

color

Color data is grouped by exterior and interior. Each item uses the same shape:

Name
name
Type
string
Description
Manufacturer color or upholstery name. Example: "Supersonic Red" or "Black, leather".
Name
rgb
Type
string
Description
Comma-separated RGB value. Example: "226,5,0".

features

Features are grouped into categories under features.standard.

Name
category
Type
string
Description
Feature category name. Example: "Power Feature", "Warranty", or "Measurements".
Name
features
Type
array
Description
List of feature items in this category.

Each feature item has:

Name
name
Type
string
Description
Feature or measurement name. Example: "hands-free entry" or "Rear leg room".
Name
value
Type
string | null
Description
Value for the feature when the source provides one. Feature flags often return null; measurements usually return a string such as "38.0 in.".

input

The input object echoes the request values used for the lookup. It can include year, make, model, trim, and allTrimOptions.

If trim is omitted, the API returns the best/default trim match for the year, make, and model. If trim is provided but not exact, the API attempts a close match. Pass allTrimOptions=1 when you need the available trims instead of a single best match. Response fields vary by vehicle and source availability.

Errors

See the Errors guide for the full list.

400 - Missing or invalid year, make, or model.
401 - API key is missing, invalid, disabled, or unauthorized.
404 - No vehicle matched the specified year, make, and model.
429 - Usage limit exceeded.
500 - Could not fetch data.

Look up vehicle data by year, make, and model when you do not have a VIN.