Search filter syntax

Filters are query parameters in the PHP bracket format. The same filters work on /search and /search/count; /cars accepts domains[] and is_leasing.

• Categorical filters take numeric IDs. See Enum values for every ID.
• currency only affects price filtering and sorting. Listing prices are always returned in their original currency.
• For an exact VIN use /cars/vin/{vin}. The vin filter on /search is a partial match.
• Omit filters you don't use. Empty values are validated and can return 422.

is_auction accepts true, false, 1 or 0 on /search, /search/count and /cars. False includes false, null and missing fields. Omit for no filter; empty or invalid values return 422. is_auction and is_leasing must match the same active listing in an enabled/selected domain. Other listings may remain in listings[]. For /cars, set the filter on the first request and follow next_url unchanged; changing or adding it mid-scroll, or sending an explicit value when cached state is unavailable, returns 422. sort=auction_nearest requires auction_at >= now; pass the same sort to /search/count.

Filter by vehicle type and configuration

vehicle_type=automobile / 1 is the default; motorcycle / 2 selects motorcycles on /search, /search/count and /cars. Use the same type for dictionaries.

Full hierarchy: brands[] → models[] → generations[] → variants[] / trims[]. Every brand/model/generation object needs id. OR between siblings and within each variant/trim list; AND between constraints in one branch. Missing or empty children mean any descendant. Each array accepts up to 100 entries. Unknown or mismatched IDs return no matches; malformed values return 422.

Legacy brands[0][models][]=573 still works. For descendants use brands[0][models][0][id]=573. Clear the legacy append field before adding structured models for that brand, or PHP will overwrite index 0.

vehicle_type=motorcycle&brands[0][id]=101&brands[0][models][0][id]=201&brands[0][models][0][generations][0][id]=301&brands[0][models][0][generations][0][variants][]=501&brands[0][models][0][generations][0][trims][]=401

Synthetic IDs: replace them with IDs from the dictionaries. Use generation branches separately to preserve specific variant/trim pairs.

Responses now include vehicle_type, generation_id, variant_id and trim_id; missing optional IDs are null. These fields participate in hash. Filters use stored root IDs only: cars without normalized IDs do not match the corresponding selections.

For /cars the type and whole hierarchy are fixed for the scroll. Follow next_url unchanged or continue with scroll_id alone. Reordering equivalent filters is allowed; changing filters or supplying them when cached state is unavailable returns 422. Start a new scroll. Old scrolls without new parameters keep their original query.

Custom listing fields

Load /listing-fields after checking the key. Definitions, constraints, operators and domain notes apply only to that key and selected domains.

Strings: eq, in, exists. Numbers and dates also support gt, gte, lt, lte. Booleans: eq or exists. Use either eq, in, exists or a range; exists is standalone. Up to 20 fields and 100 values per in.

All custom conditions, selected domains and activity must match the same listing. Zero and false are real values. Arrays match a qualifying element. Unknown or unavailable fields/operators return 422.

Only filterable fields can be queried. Indexed values are in listings[].custom_fields; stored-only values remain in listings[].source_data. Publication enables filters; subsequent normal imports fill values. Old documents are not backfilled.

For /cars, keep conditions for the whole scroll. An incompatible field contract or lost filter state requires a new scroll. Sorting and aggregations by these fields are not supported.

Use FIELD_KEY from your authorized catalogue in these examples. For money comparisons, also provide the native listing currency; this does not use Buy Now conversion.

Source-specific historical market estimates are informational stored-only values. They describe comparable sales, not this listing’s asking price, bid or reserve. Check the field description, comparison criteria and observation date; do not infer a currency from the listing. Registered numeric values can be null when no estimate is available.

custom_fields[FIELD_KEY][gte]=2
custom_fields[FIELD_KEY][in][]=a&custom_fields[FIELD_KEY][in][]=b
custom_fields[FIELD_KEY][eq]=false
custom_fields[FIELD_KEY][lte]=15000&custom_fields[FIELD_KEY][currency]=cad