CarsXECarsXE

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

Who uses this API

Configurators, parts catalogs, and listing platforms call this endpoint when they have year, make, and model (and maybe trim) but no VIN — they still need structured specs, colors, features, or pricing.

Use cases

B2B

B2C

Parameters

ParameterRequiredDescription
yearYesVehicle model year, numeric, between 1900 and the current model year plus one
makeYesManufacturer, for example Toyota, Ford, or BMW
modelYesVehicle model, for example Camry, F-150, or X5
trimNoTrim hint, for example XLE or Sport; fuzzy matched when possible
exact_matchNoDefault false. Use true or 1 for exact make/model and supplied trim matching; false or 0 retains fuzzy selection. Values are case-insensitive.
allTrimOptionsNoPass 1 to return all trim options for the year, make, and model

Strict matching and substitution detection

Use exact_match=true to reject sibling trims and models. Exact matching ignores case and leading, trailing, or repeated whitespace, while preserving punctuation. The trim must equal either the complete short trim (for example, Light Long Range) or the complete stored style string, including body and engine details. Light does not match Light Long Range, and F-150 does not match F-150 Lightning.

Without a trim, including a whitespace-only trim, strict mode requires exact make/model and selects the most popular eligible style, or the first style in stable name/ID order. With allTrimOptions=1, strict mode returns only eligible styles. If neither data source contains an eligible match, the API returns the existing HTTP 404 response with success:false. Invalid exact_match values return HTTP 400; arrays and objects are invalid.

Every successful response includes top-level match_exact: true when make, model, and the requested trim/style all match, false when any differs, or null when no trim was requested. input.exact_match echoes the effective boolean. This flag is also available with default fuzzy matching, so integrations can detect substitutions without parsing bestMatch.name.

curl -G https://api.carsxe.com/v1/ymm \
  -d key=YOUR_API_KEY -d year=2025 -d make=Toyota -d model=Camry \
  -d trim=LE -d exact_match=true

For a complete style string, preserve its punctuation and use URL encoding, for example --data-urlencode 'trim=XL Regular Cab 6.5 ft. SB (2.7L 6cyl Turbo 10A)' with the corresponding year, make, and model.

A default fuzzy request for LT that returns LTZ Crew Cab ... reports "match_exact": false. The same request with exact_match=true returns HTTP 404 unless an exact LT style is available. Fuzzy matching searches substring-filtered style candidates and chooses the closest style string; it does not perform an unrestricted fallback to the most popular trim. Without a trim, the existing most-popular/first-result behavior applies.

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.

Every successful response includes success and match_exact. Other fields depend on the response. Availability varies by vehicle, trim, and source coverage.

bestMatch

The bestMatch object contains the matched vehicle and trim data.

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. Each option includes the same trim_id field as bestMatch.

trim_id is an opaque identifier for the complete year/make/model/style combination, returned on bestMatch and every trimOptions entry. Store and compare it without parsing it. The same normalized values produce the same ID across requests and data sources; changes to pricing or features do not change it. Material changes to year, make, model, or the full style description produce a different ID. Identity guarantees apply to records with all four values present. Styles sharing a short trim name can have different IDs.

name remains the full style description. trim_id is response-only and is not accepted as a request parameter; existing trim matching behavior is unchanged.

Example option list when allTrimOptions=1:

{
  "trimOptions": [
    {
      "trim_id": "ymm_style_v1_31ec8f9ad439d778b2dcb4dc8c0cfdafdf4ddf869d03d377de63684a02ab2eab",
      "make": "Toyota",
      "model": "Camry",
      "year": "2023",
      "name": "XLE 4dr Sedan (3.5L 6cyl 8A)"
    }
  ]
}

color

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

features

Features are grouped into categories under features.standard.

Each feature item has:

input

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

If trim is omitted, the API returns the best/default trim match for the year, make, and model. With default fuzzy matching, a non-exact trim attempts a close match within substring-filtered candidates. With exact_match=true, an unavailable exact trim returns HTTP 404. 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.