Use /v1/ymm-options to power cascading dropdowns in your own UI. Each request returns exactly one list — years, makes, models, variants (combined model + trim display strings, e.g. "Tacoma TRD Pro"), or trims (shorter manufacturer trim names when you explicitly request dimension=trims).

Typical flow: start with no filters to list years → add year for makes → add make for models → add model for variants. One API call per dropdown level.

Need full vehicle specs for a selected year, make, and model? Use Year Make Model (/v1/ymm) instead.

Endpoint: /v1/ymm-options

Who uses this API

Configurators, quoting tools, and listing forms call this endpoint to populate cascading Year / Make / Model / Variant dropdowns — one list per request, without decoding a VIN.

Use cases

B2B

Quote and intake forms: Drive year → make → model → variant selects so staff never free-type a YMM.
Parts catalogs: Load the next dropdown layer as a technician narrows the vehicle.
Dealer websites: Power inventory search filters from the same option lists.

B2C

Consumer configurators: Let a shopper pick year, make, model, and variant before seeing specs or value.
Listing creation: Guide a private seller through dropdowns instead of a VIN when they do not have one handy.

Parameters

Parameter	Required	Description
`key`	Yes	Your CarsXE API key
`dimension`	No	One of `years`, `makes`, `models`, `trims`, or `variants`. When set, the response contains exactly that array when the required filters are present. When omitted, the response layer is inferred from `year`, `make`, and `model`.
`year`	No	Filter to a specific manufacturing year. Required when filtering by `model` without `make`.
`make`	No	Filter to a manufacturer (e.g. `Toyota`, `Ford`, `Lexus`). Required for `dimension=models`.
`model`	No	Filter to a model (e.g. `Camry`, `F-150`, `LX`). Required for `dimension=trims` and for `dimension=variants` unless both `year` and `make` are set (bulk variant list).

Automatic response shape (no `dimension`)

Omit dimension and the API returns one array inferred from your filters:

`make`?	`model`?	`year`?	Returns
—	—	—	`years`
—	—	✓	`makes`
✓	—	*	`models`
✓	✓	*	`variants`
—	✓	—	400 — `year` required when `model` is given without `make`
—	✓	✓	`variants` if that model name maps to one make that year; 400 if ambiguous (add `make`)

The API never returns more than one layer per response. To populate both a model list and a variant list, make two calls.

Bulk variant list

Set dimension=variants with year + make (no model) to fetch every variant for that make in one flat array — useful for client-side search or filter UIs.

Billing

Most requests cost 1 unit.

Exception: dimension=variants with year + make and no model costs 1 unit per model. The response includes modelCount, the number of distinct models, which is also the amount billed — with a minimum of 1 unit even when zero models match.

Example: 82 variant strings across 12 models → modelCount: 12 → 12 units.

Example

Populate a cascading dropdown

Code

# Step 1 — list years (no filters)
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY

# Step 2 — makes for a year
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d year=2026

# Step 3 — models for a make
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d make=Toyota

# Step 4 — variants for year + make + model
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d year=2026 \
  -d make=Toyota \
  -d model=Tacoma

# Bulk variants for a make + year (billed per model — see modelCount)
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d dimension=variants \
  -d year=2025 \
  -d make=Lexus

Response

Top-level shape

{

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

"message": "optional guidance when the returned layer differs",// optional

"modelCount": 12,// bulk variants only — units billed

}

Click input or a returned array to expand sample values. For the full interactive reference, try it live in the API Reference.

Each successful response includes success: true and exactly one of years, makes, models, trims, or variants. The message field is optional guidance when the returned layer differs from what you requested.

Name
success
Type
boolean
Description
true on a successful lookup.
Name
input
Type
object
Description
Echoes back only the query parameters you submitted.
Name
message
Type
string
Description
Optional guidance when the returned layer differs from the requested dimension, or when explaining what to add next for better results.
Name
years / makes / models / trims / variants
Type
array
Description
Distinct values for the requested (or inferred) layer. Only one array is present per response.
Name
modelCount
Type
number
Description
Present only for bulk variants (dimension=variants + year + make, no model). Equals the number of distinct models, which is also the amount billed — except a zero-match query, which returns modelCount: 0 but still bills a minimum of 1 unit.

variants vs trims

variants returns display-ready strings like "Tacoma TRD Pro". trims returns shorter manufacturer trim names. Both need a model (or disambiguating year/make) for single-vehicle lookups; only dimension=variants accepts year + make without model for a bulk list. For dropdown menus, use inferred responses or dimension=variants.

Every request requires a valid, active CarsXE API key and counts toward your Year Make Model Options quota — a separate bucket from Year Make Model. Most calls cost 1 unit; bulk variants (dimension=variants + year + make) cost 1 unit per model (modelCount).

Errors

Status	When it happens
`400`	Invalid `dimension`, missing required filters, or ambiguous `model` without `make`
`401`	Missing or invalid API key
`429`	Usage limit exceeded
`500`	Could not fetch data

See the Errors guide for general error handling guidance.

FAQ

How is usage billed?

Most requests cost 1 unit. Exception: dimension=variants with year + make and no model costs 1 unit per model. Check modelCount in the response — that is the amount billed, with a minimum of 1 unit.

Why did I get models when I asked for variants?

You requested dimension=variants (or trims) with only make and no year. The API returns models for that make and a message telling you to add model next. With dimension=variants, year, and make, you get variants directly.

What is the difference between trims and variants?

variants returns display-ready strings like "Tacoma TRD Pro". trims returns shorter manufacturer trim names. Only dimension=variants accepts year + make without model for a bulk list.