Connect key
GET/searchVehicles

Search vehicles

Filter active vehicles across your enabled sources. Results are lightweight: each car carries report flags, not report bodies.

  • 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.
  • is_auction accepts true/false/1/0. False includes false, null and missing flags; omit for no filter. It must match the same active listing as is_leasing in the enabled/selected domains. Other listings may remain in listings[].
  • perPage is 2–50 (default 50). perPage=1 returns 422.
  • Keep page × perPage at or below 10,000. To read further, use /cars.
  • data can contain perPage + 1 cars, and meta.total stops at 10,000. Use /search/count for exact totals.
  • sort=auction_nearest selects only cars with an active listing in the enabled/selected domains with auction_at >= now. Send the same sort to /search/count.
  • Price sorts (cheaper, expensive) compare prices in currency.
  • Use price for Buy Now, current_bid for the current auction bid, and /listing-fields for authorized additional amounts. Money comparisons require the native currency inside each custom-field condition; source amounts are not converted.

Query parameters

48
Query, paging and scope
vinstring1–19 chars

Case-insensitive partial VIN. For an exact 16–19 character VIN, use /cars/vin/{vin}.

pageinteger≥ 1 · default 1

Page number. For /search, explicitly pass perPage and keep page × perPage ≤ 10000. /search/count ignores pagination and skips this offset check.

perPageinteger2–50 · default 50

Search page size: minimum 2, maximum 50. perPage=1 returns 422; use perPage=2 to fetch a small sample. Omitted or null pagination values use page=1 and perPage=50, including the search result-window check. Invalid values return 422.

sortstring

Sort order. Price sorting requires a resolved currency. auction_nearest selects only cars with an active listing in an enabled/selected domain with auction_at >= now; past dates do not participate in sorting. Pass the same sort to /search/count for a matching count.

currencystring3 chars · default usd

Case-insensitive currency code for price filtering/sorting. Must exist in the currency dictionary. Does not convert serialized listing prices.

currency_idinteger≥ 1

Optional internal currency ID; overrides currency.

domains[]integer[]≥ 1

Optional source scope. Use IDs returned by GET /domains. Omit to use all enabled domains. Repeat the bracketed parameter: domains[]=33&domains[]=34. Every ID must be enabled for this key.

vehicle_typestringdefault automobile

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

langstring

Response locale. Option translations are also limited by the account languages. The page selects its current language automatically.

Brand, model and location
brands[0][id]integer≥ 1

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.

brands[0][models][]integer[]≥ 1 · ≤ 100 items

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.

brands[0][models][0][id]integer≥ 1

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.

brands[0][models][0][generations][0][id]integer≥ 1

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.

brands[0][models][0][generations][0][variants][]integer[]≥ 1 · ≤ 100 items

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.

brands[0][models][0][generations][0][trims][]integer[]≥ 1 · ≤ 100 items

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.

countries[0][id]integer

First internal country ID from /countries. Additional countries use countries[1][id], etc.

countries[0][regions][]integer[]

Optional internal region IDs belonging to the first country.

Ranges
seatsinteger1–200

Exact seating capacity.

price_fromint64≥ 0

Minimum listing price in the selected currency. Maximum 9223372036854775807 (signed 64-bit integer); values beyond JavaScript safe integers must be preserved as decimal text by clients.

price_toint64≥ 1

Maximum listing price in the selected currency. Maximum 9223372036854775807 (signed 64-bit integer); values beyond JavaScript safe integers must be preserved as decimal text by clients.

year_frominteger1,800–3,000

Minimum production year.

year_tointeger1,800–3,000

Maximum production year.

odometer_frominteger0–999,999,999

Minimum mileage in kilometres.

odometer_tointeger0–999,999,999

Maximum mileage in kilometres.

engine_volume_frominteger0–999,999,999

Minimum engine displacement.

engine_volume_tointeger0–999,999,999

Maximum engine displacement.

power_hp_frominteger0–100,000

Minimum power in horsepower.

power_hp_tointeger1–100,000

Maximum power in horsepower.

Flags
is_leasingboolean

Optional leasing filter. Send true (or 1) for listings explicitly marked is_leasing=true. Send false (or 0) to exclude true, including stored false, null and missing fields. Omit for no leasing filter; empty or invalid values return 422. A car must have at least one matching active listing in the enabled/selected domain scope. Other listings can remain in the response, so cars with mixed listing types can match both values. For /cars, set this on the first request and follow next_url unchanged; false is preserved. Continuing with only scroll_id retains the filter. Changing or adding the filter mid-scroll returns 422. If cached filter state is lost or the scroll predates this parameter, an explicit value returns 422; start a new scroll.

is_auctionboolean

Optional auction filter. Send true (or 1) for listings explicitly marked is_auction=true. Send false (or 0) to exclude true, including stored false, null and missing fields. Omit for no auction filter; empty or invalid values return 422. Combined is_auction and is_leasing must match the same listing. A car must have at least one matching active listing in the enabled/selected domain scope. Other listings can remain in the response, so cars with mixed listing types can match both values. For /cars, set this on the first request and follow next_url unchanged; false is preserved. Continuing with only scroll_id retains the filter. Changing or adding the filter mid-scroll returns 422. If cached filter state is lost or the scroll predates this parameter, an explicit value returns 422; start a new scroll.

keys_availableinteger

Listing has keys. Send 1 (true) or 0 (false). Omit for either value; strings "true"/"false" are rejected.

is_manufacturer_certifiedinteger

Listing is certified by the manufacturer or official dealer program. Send 1 (true) or 0 (false). Omit for either value; strings "true"/"false" are rejected.

has_inspectionsinteger

Root car has a public inspection. Send 1 (true) or 0 (false). Omit for either value; strings "true"/"false" are rejected.

has_history_reportsinteger

A listing in the selected domain scope has a public history report. Send 1 (true) or 0 (false). Omit for either value; strings "true"/"false" are rejected.

Categories
body_types[]integer[]

Repeat to match any of the values.

colors[]integer[]

Repeat to match any of the values.

fuels[]integer[]

Repeat to match any of the values.

transmissioninteger

One value.

seller_typeinteger

One value.

steering_wheel_positioninteger

One value.

airbagsinteger

One value.

damages[]integer[]

Repeat to match any of the values.

conditions[]integer[]

Repeat to match any of the values.

availabilities[]integer[]

Repeat to match any of the values.

emissions[]integer[]

Repeat to match any of the values.

drive_wheels[]integer[]

Repeat to match any of the values.

interior_colors[]integer[]≤ 100 items

Interior color IDs from the colors dictionary. OR within the list; missing values do not match. Applies to /search, /search/count and /cars. Keep unchanged during scroll.

cylinders[]integer[]1–99 · ≤ 99 items

Exact cylinder counts (1–99), OR within the list; unknown counts do not match. Applies to /search, /search/count and /cars. Keep unchanged during scroll.

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

Custom listing fields

Connect a key to see the fields available to your domains.

Returns · A page of Car objects in data, with links and meta. The inspections and vehicle_history_reports arrays are omitted.
GET/search
curl -g "https://api.auctionsapi.com/search?perPage=5&api_key=$CARS_API_KEY" \
  -H "Accept: application/json"
ExamplesRecorded
{3 keys
"data": [1 item
0: {21 keys
"id": "l_eCJb-8zB_XcJ-z6Y7oZWjw"
"has_inspections": true
"has_history_reports": true
"year": 2014
"month": 4
"vin": "wddhf0cb3ea952710"
"brand": {2 keys}
"model": {2 keys}
"engine_volume": 2143
"seats": 5
"body_type": {2 keys}
"transmission": {2 keys}
"transmission_steps": 6
"fuel": {2 keys}
"color": {2 keys}
"power_hp": 170
"market_origin": {2 keys}
"badge": "E220 CDI Avantgarde"
"option_ids": [53 items]
"listings": [1 item]
"hash": "093563801f92d9cfa23a07346b26b69db32df8da05d7c5ee60fa5fd876a7fe0b"
}
]
"links": {4 keys}
"meta": {7 keys}
}

Get API access

Connect your key to run every request on these pages against your own data. No key yet? Ask us for a demo key: the same JSON as the paid plans.

I have a key