Auction API Documentation

Overview

Auction API comprises information about vehicle listings that are currently available through enabled data sources. The data includes vehicle specifications, pricing, seller details, location, images, listing URLs, and auction-related fields when available.

Your API key is issued separately and must be sent as the api_key GET parameter on every endpoint.

Coverage

Active vehicle listings available under your subscription and limited by enabled data sources.

Delivery

Data is delivered with Elasticsearch scroll queries, optimized for batch processing of large datasets.

Synchronization

Only currently active, non-archived vehicles are returned by the stream endpoint.

Access control

Every request is validated by API key, active subscription, enabled data sources, and IP whitelist when enabled.

HTTP Request

Endpoint

requestGET

cars stream

GEThttps://api.auctionsapi.com/cars?api_key=YOUR_API_KEY

Example — Laravel / HTTP Client

Target:

Client:

SyncCars.php

1use Illuminate\Support\Facades\Http;2 3$response = Http::acceptJson()4    ->timeout(60)5    ->get('https://api.auctionsapi.com/cars', [6        'api_key' => 'YOUR_API_KEY',7    ]);8 9return $response->json();

API endpoints

GET/carsStep 1

Sync start

Start sync

api_keylimitscroll_time

https://api.auctionsapi.com/cars?api_key=YOUR_API_KEY&limit=1000&scroll_time=10

GET/carsStep 2

Sync next

Continue sync

api_keyscroll_id

https://api.auctionsapi.com/cars?api_key=YOUR_API_KEY&scroll_id=SCROLL_ID

GET/search

Keyword search

api_keyquerypageperPagesort

https://api.auctionsapi.com/search?api_key=YOUR_API_KEY&query=toyota&page=1&perPage=20&sort=newest

GET/search

Filtered search

priceyearenumsbrands

https://api.auctionsapi.com/search?api_key=YOUR_API_KEY&price_from=5000&price_to=15000&currency_id=1&year_from=2015&year_to=2020&body_types[]=5&fuels[]=1&colors[]=13&transmission=1&drive_wheels[]=3&brands[0][id]=10&brands[0][models][]=101

GET/brands

Reference

Brands

api_key

https://api.auctionsapi.com/brands?api_key=YOUR_API_KEY

GET/models/{brand_id}

Reference

Models

brand_idapi_key

https://api.auctionsapi.com/models/58?api_key=YOUR_API_KEY

Pagination workflow

Start with /cars without scroll_id.
The response includes scroll_id and next_url.
If next_url is not empty, keep requesting it until it is empty or the API returns no more data.
If a vehicle has not been returned in the last 24 hours, mark it as archived or remove it from your database.

GET Parameters

Parameter	Endpoint	Type	Default / limits	Description
`api_key`	`All endpoints`	`string`	Default: -	Your unique API key. Must be passed as a GET parameter.
`scroll_time`	`/cars`	`int`	Default: 10 Limits: Max: 15 minutes	Duration of the scroll session.
`limit`	`/cars`	`int`	Default: 1000 Limits: Max: 2000	Number of cars per batch.
`scroll_id`	`/cars`	`string`	Default: -	Use this to fetch the next batch of data.
`page`	`/search`	`int`	Default: 1 Limits: Min: 1	Page number.
`perPage`	`/search`	`int`	Default: 50 Limits: Min: 2, Max: 50	Items per page.
`sort`	`/search`	`string`	Default: newest Limits: See sort options	Sort order.
`query`	`/search`	`string`	Default: - Limits: Max length: 200	Full-text search query.
`price_from`	`/search`	`int`	Default: - Limits: Min: 0	Minimum price, inclusive.
`price_to`	`/search`	`int`	Default: - Limits: Min: 1	Maximum price, inclusive.
`currency_id`	`/search`	`int`	Default: - Limits: Min: 1	Currency for price filtering. Ignored if no price range is provided.
`year_from`	`/search`	`int`	Default: - Limits: Min: 1800, Max: 3000	Model year from, inclusive.
`year_to`	`/search`	`int`	Default: - Limits: Min: 1800, Max: 3000	Model year to, inclusive.
`odometer_from`	`/search`	`int`	Default: - Limits: Min: 0, Max: 999999999	Odometer from, inclusive.
`odometer_to`	`/search`	`int`	Default: - Limits: Min: 0, Max: 999999999	Odometer to, inclusive.
`engine_volume_from`	`/search`	`int`	Default: - Limits: Min: 0, Max: 999999999	Engine volume from, inclusive.
`engine_volume_to`	`/search`	`int`	Default: - Limits: Min: 0, Max: 999999999	Engine volume to, inclusive.
`power_hp_from`	`/search`	`int`	Default: - Limits: Min: 0, Max: 100000	Horsepower from, inclusive.
`power_hp_to`	`/search`	`int`	Default: - Limits: Min: 1, Max: 100000	Horsepower to, inclusive.
`brands`	`/search`	`array<object>`	Default: - Limits: id, optional models[]	Brand filter. If models are omitted, matches any model inside the selected brand.
`body_types`	`/search`	`int[]`	Default: - Limits: See enums	Body type IDs.
`colors`	`/search`	`int[]`	Default: - Limits: See enums	Color IDs.
`fuels`	`/search`	`int[]`	Default: - Limits: See enums	Fuel IDs.
`seller_type`	`/search`	`int`	Default: - Limits: See enums	Seller type ID.
`steering_wheel_position`	`/search`	`int`	Default: - Limits: See enums	Steering wheel position ID.
`transmission`	`/search`	`int`	Default: - Limits: See enums	Transmission ID.
`airbags`	`/search`	`int`	Default: - Limits: See enums	Airbag state ID.
`damages`	`/search`	`int[]`	Default: - Limits: See enums	Damage IDs.
`conditions`	`/search`	`int[]`	Default: - Limits: See enums	Condition IDs.
`availabilities`	`/search`	`int[]`	Default: - Limits: See enums	Availability IDs.
`emissions`	`/search`	`int[]`	Default: - Limits: See enums	Emission standard IDs.
`drive_wheels`	`/search`	`int[]`	Default: - Limits: See enums	Drive wheel IDs.
`keys_available`	`/search`	`boolean`	Default: - Limits: true/false or 1/0	Filter by key availability.
`brand_id`	`/models/{brand_id}`	`int`	Default: - Limits: Path parameter	Brand ID used to return models for a specific brand.

Sort options

Value	Description
`newest`	Newest listings first.
`oldest`	Oldest listings first.
`cheaper`	Lowest price first.
`expensive`	Highest price first.
`odometer_asc`	Lowest odometer first.
`odometer_desc`	Highest odometer first.
`year_asc`	Oldest model year first.
`year_desc`	Newest model year first.
`auction_nearest`	Nearest auction date first.

Array and nested parameters

Simple arrayscolors[]=13&colors[]=15&fuels[]=1&fuels[]=4

Brands and modelsbrands[0][id]=10&brands[0][models][]=101&brands[0][models][]=102&brands[1][id]=12

If models are omitted, the filter matches any model inside the selected brand. For search pagination, page * perPage must be less than or equal to 10000.

Enum values

Use the numeric ID in your query parameters. For example, colors[]=13 means white, and transmission=1 means automatic.

Body types

body_types

1Sedan2Wagon3Coupe4Pickup5SUV6Cabrio7Van11Hatchback12Roadster13Limousine20Liftback22Hearse27Sport car

Colors

colors

1Silver2Purple3Orange4Green5Red6Gold8Brown9Grey10Turquoise11Blue12Bronze13White14Cream15Black16Yellow17Beige18Pink100Two colors

Fuels

fuels

1Diesel2Electric3Hybrid4Gasoline5Gas6Flexible7Hydrogen8Ethanol

Seller type

seller_type

1Individual2Dealer

Steering wheel position

steering_wheel_position

1Left2Right

Transmission

transmission

1Automatic2Manual

Airbags

airbags

1Intact2Deployed3Missing

Damages

damages

1Side2Theft3Burn4Electric5Vandalized6Water7Top roof8Transmission9Suspension10Biohazard11Cash for clunkers12Repossession13Rollover14All over15Engine16Frame17Front18Rear19Front and rear20Hail21Mechanical22Minor dents/scratches23VIN24Normal wear25Rejected or partial repair26Storm27Stripped28Undercarriage

Conditions

conditions

1Used2New3Damaged

Availability

availabilities

1In stock2In transit3On order

Emissions

emissions

1Euro 12Euro 23Euro 34Euro 45Euro 56Euro 67Zev

Drive wheels

drive_wheels

1Rear2Front3All

JSON Response

The response includes normalized vehicle information, listing data, images, price, location, seller type, condition, auction fields, and pagination data for continuing the stream.

Response Fields

Parameter	Description
`data`	Array of normalized vehicle records available under your subscription, or an empty array when there is no more stream data.
`id`	Internal AuctionsAPI vehicle identifier.
`brand / model`	Normalized make and model objects with IDs and names.
`engine_volume`	Engine displacement when available.
`body_type / transmission / fuel / color`	Normalized enum objects with ID and name.
`listings`	Source listing records with listing URL, title, price, seller type, images, dates, and status.
`external`	Original listing identifier, source domain placeholder, and listing URL.
`price`	Listing price, currency, negotiable flag, and optional price history.
`location`	Listing location metadata and coordinates when available.
`condition / damage / auction fields`	Condition, auction date, bid, keys, damage, airbag state, and document fields when available.
`scroll_id`	Pagination token returned by the stream endpoint when more batches are available.
`next_url`	Ready-to-call URL for the next batch. Stop when it is empty or there is no more data.
`hash`	Stable hash of the normalized vehicle data.
`message`	Returned by the stream endpoint when no more data is available.

Response200 OK

application/json

1{2  "data": [3    {4      "id": "0z2OgJ0B0FUJVEfmXKRZ",5      "year": 2022,6      "vin": "wba5p9c02nfm40627",7      "brand": {8        "id": 16,9        "name": "BMW"10      },11      "model": {12        "id": 93,13        "name": "3er"14      },15      "body_type": {16        "name": "sedan",17        "id": 118      },19      "transmission": {20        "name": "automatic",21        "id": 122      },23      "transmission_steps": 5,24      "fuel": {25        "name": "gasoline",26        "id": 427      },28      "color": {29        "name": "grey",30        "id": 931      },32      "market_origin": {33        "name": "europe",34        "id": 135      },36      "drive_wheels": {37        "name": "all",38        "id": 339      },40      "badge": "330e xDrive Plug-In Hybrid - Leather - Sunroof !!",41      "listings": [42        {43          "external": {44            "id": "EXTERNAL_LISTING_ID",45            "domain": {46              "id": 1000,47              "name": "{domain.com}"48            },49            "url": "https://{domain.com}/vehicle-listing/example"50          },51          "archived": false,52          "title": {53            "en": "2022 BMW 3 Series 330e xDrive Plug-In Hybrid - Leather - Sunroof !!"54          },55          "odometer": 39650,56          "location": {57            "iso": "ca",58            "position": {59              "lon": -113.64258,60              "lat": 60.1086761            }62          },63          "images": [64            {65              "preview": "https://{image-domain.com}/vehicles/example-1-preview.jpg",66              "original": "https://{image-domain.com}/vehicles/example-1.jpg"67            },68            {69              "preview": "https://{image-domain.com}/vehicles/example-2-preview.jpg",70              "original": "https://{image-domain.com}/vehicles/example-2.jpg"71            },72            {73              "preview": "https://{image-domain.com}/vehicles/example-3-preview.jpg",74              "original": "https://{image-domain.com}/vehicles/example-3.jpg"75            },76            {77              "preview": "https://{image-domain.com}/vehicles/example-4-preview.jpg",78              "original": "https://{image-domain.com}/vehicles/example-4.jpg"79            },80            {81              "preview": "https://{image-domain.com}/vehicles/example-5-preview.jpg",82              "original": "https://{image-domain.com}/vehicles/example-5.jpg"83            }84          ],85          "video": null,86          "created_at": "2026-04-12T07:18:25.915404Z",87          "last_seen_at": "2026-04-29T07:59:47.901334Z",88          "updated_at": "2026-04-29T07:59:47.901337Z",89          "price": {90            "price": 30888,91            "currency": {92              "id": 28,93              "name": "cad"94            },95            "negotiable": false,96            "history": null97          },98          "seller_type": {99            "name": "dealer",100            "id": 2101          },102          "is_auction": false,103          "current_bid": null,104          "auction_at": null,105          "availability": null,106          "condition": {107            "name": "used",108            "id": 1109          },110          "keys_available": null,111          "damage": null,112          "second_damage": null,113          "airbag_state": null,114          "document_id": null,115          "description": "Sample 2022 BMW 330e xDrive Plug-In Hybrid listing with leather, sunroof, navigation, reverse camera, heated seats, and driver assistance features."116        }117      ],118      "hash": "60b52121bedf682865247f58ac068d217d2bc7d4dc3db88d2f7856b0dfa6e79e"119    }120  ],121  "scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAx...",122  "next_url": "https://api.auctionsapi.com/cars?scroll_id=DXF1ZX...&api_key=YOUR_API_KEY"123}

No more stream data

Response200 OK

application/json

1{2  "scroll_id": null,3  "data": [],4  "message": "No more data"5}

Brand list response

Response200 OK

application/json

1[2  {3    "id": 9,4    "name": "Audi"5  },6  {7    "id": 13,8    "name": "Bentley"9  },10  {11    "id": 16,12    "name": "BMW"13  },14  {15    "id": 88,16    "name": "Mercedes-Benz"17  },18  {19    "id": 110,20    "name": "Porsche"21  }22]

Model list response

Response200 OK

application/json

1[2  {3        "id": 1665,4        "name": "X5",5        "generations": [6            {7                "name": "III (F15)",8                "from": 2013,9                "to": 201810            },11            {12                "name": "IV (G05)",13                "from": 2018,14                "to": 202215            },16            ...17        ]18    },19  {20    "id": 102,21    "name": "X6",22    "generations": []23  }24]

Error Responses

error

When an error occurs, the API returns an error status with a code and message.

Code	Description	Resolution
`400`	scroll_time must be less than 15.	Use scroll_time up to 15 minutes.
`400`	limit must be less than 2000.	Use limit up to 2000 cars per batch.
`403`	please add your api_key in get param.	Add api_key as a GET parameter.
`403`	wrong api key.	Check that the API key is valid.
`403`	your api subscription is not active.	Activate or renew the subscription.
`403`	ip address is not in whitelist.	Send the request from an allowed IP or update the whitelist.
`403`	you don't have any data in your subscription.	Make sure data sources are enabled for the subscription.
`422`	page * perPage exceeds 10000 for search and the API returns an offset error.	Reduce page or perPage so the offset stays within 10000.
`500`	Unexpected server error.	Retry the request or contact support if the issue persists.

Auction APIDocumentation

Overview

Coverage

Delivery

Synchronization

Access control

HTTP Request

Start sync

Continue sync

Keyword search

Filtered search

Brands

Models

GET Parameters

Body types

Colors

Fuels

Seller type

Steering wheel position

Transmission

Airbags

Damages

Conditions

Availability

Emissions

Drive wheels

JSON Response

Error Responses