---
title: "Vehicle Scan"
description: "The Vehicle Scan tool over the API: saved vehicle requests and the auction and classifieds offers that match them. These are the same requests the account sees in the portal. Scope: vehiclescan, granted per contract, and the key’s account must also be granted Vehicle Scan."
canonical: "https://thecarapi.com/docs/vehiclescan"
contract_version: "2026-10-05"
api_base: "https://api.thecarapi.com"
source: "https://thecarapi.com/docs/vehiclescan.md"
---

# Vehicle Scan

The Vehicle Scan tool over the API: saved vehicle requests and the auction and classifieds offers that match them. These are the same requests the account sees in the portal. Scope: vehiclescan, granted per contract, and the key’s account must also be granted Vehicle Scan.

## GET /api/vehiclescan/access

Whether the key’s account may use Vehicle Scan, and its limits.

**Scope:** `vehiclescan`

### Example requests

```http
GET https://api.thecarapi.com/api/vehiclescan/access
```

### Example response

```json
{
  "success": true,
  "limits": {
    "requests": 20,
    "vehicles_per_request": 5,
    "matches_per_request": 200
  }
}
```

**Notes.** limits: requests per account, vehicles per request, matches returned per request. Needs the key to be linked to a portal account that has been granted the tool in the admin; a key without that grant gets 403 even with the scope. Responses are the tool’s own body ({ success: true, ... } or { success: false, message }) — the same backend the portal page uses — so they carry no contract_version envelope. Read X-Request-ID from the header.

## GET /api/vehiclescan/options

Makes, fuels and gearboxes for a request, or one make’s models.

**Scope:** `vehiclescan`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `brand` | Query string | string | no | `BMW` | /api/vehiclescan/options -> makes | Returns this make’s models instead. |
| `country` | Query string | string | no | `DE` | Your user’s market. | Narrows the options to one country. |

### Example requests

```http
GET https://api.thecarapi.com/api/vehiclescan/options
```

```http
GET https://api.thecarapi.com/api/vehiclescan/options?brand=BMW
```

### Example response

```json
{
  "success": true,
  "makes": [
    "BMW"
  ],
  "fuels": [
    "Diesel"
  ],
  "gearboxes": [
    "Automatic"
  ]
}
```

## GET /api/vehiclescan/requests

The account’s vehicle requests.

**Scope:** `vehiclescan`

### Example requests

```http
GET https://api.thecarapi.com/api/vehiclescan/requests
```

### Example response

```json
{
  "success": true,
  "requests": [
    {
      "id": 5,
      "active": true,
      "criteria": [
        {
          "make": "BMW",
          "model": "320d",
          "year_from": 2018
        }
      ],
      "matches_found": 41
    }
  ]
}
```

## POST /api/vehiclescan/requests

Save a vehicle request.

**Scope:** `vehiclescan`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `criteria` | JSON body | object[] | yes | `[{"make": "BMW", "model": "320d", "year_from": 2018}]` | /api/vehiclescan/options | 1 to 5 vehicles, each with a make. |

### Example requests

```http
POST https://api.thecarapi.com/api/vehiclescan/requests
{"criteria": [{"make": "BMW", "model": "320d", "year_from": 2018}]}
```

### Example response

```json
{
  "success": true,
  "id": 5,
  "matches_found": 41
}
```

**Notes.** Offers already listed are matched at once (matches_found) but not marked new; the scraper cycle marks later ones is_new. Up to 20 requests per account.

## PUT /api/vehiclescan/requests/{request_id}

Replace a request’s vehicles.

**Scope:** `vehiclescan`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `request_id` | URL path | integer | yes | `5` | /api/vehiclescan/requests -> requests[].id | The request id. |
| `criteria` | JSON body | object[] | yes | `[{"make": "BMW", "model": "330d"}]` | /api/vehiclescan/options | 1 to 5 vehicles, each with a make. Matching restarts from the offers listed now. |

### Example requests

```http
PUT https://api.thecarapi.com/api/vehiclescan/requests/5
{"criteria": [{"make": "BMW", "model": "330d"}]}
```

### Example response

```json
{
  "success": true,
  "id": 5,
  "matches_found": 12
}
```

## DELETE /api/vehiclescan/requests/{request_id}

Delete a request.

**Scope:** `vehiclescan`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `request_id` | URL path | integer | yes | `5` | /api/vehiclescan/requests -> requests[].id | The request id. |

### Example requests

```http
DELETE https://api.thecarapi.com/api/vehiclescan/requests/5
```

### Example response

```json
{
  "success": true
}
```

## POST /api/vehiclescan/requests/{request_id}/active

Pause or resume a request.

**Scope:** `vehiclescan`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `request_id` | URL path | integer | yes | `5` | /api/vehiclescan/requests -> requests[].id | The request id. |
| `active` | JSON body | boolean | yes | `false` | Your choice. | false pauses matching, true resumes it. |

### Example requests

```http
POST https://api.thecarapi.com/api/vehiclescan/requests/5/active
{"active": false}
```

### Example response

```json
{
  "success": true
}
```

## GET /api/vehiclescan/requests/{request_id}/matches

Offers matching a request.

**Scope:** `vehiclescan`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `request_id` | URL path | integer | yes | `5` | /api/vehiclescan/requests -> requests[].id | The request id. |

### Example requests

```http
GET https://api.thecarapi.com/api/vehiclescan/requests/5/matches
```

### Example response

```json
{
  "success": true,
  "offers": [
    {
      "site_name": "openlane",
      "auction_id": 11409652,
      "is_new": true
    }
  ],
  "retail": [
    {
      "reference_id": "tp-91744022",
      "is_new": false
    }
  ],
  "limited": false
}
```

### Response fields

| Field | Type | Meaning |
| --- | --- | --- |
| `offers / retail` | object[] | Auctions and classifieds respectively, up to 200 each. is_new marks offers found since the request was saved; dismissed offers are left out. |
| `limited` | boolean | True when there were more than 200 of either. |

## DELETE /api/vehiclescan/requests/{request_id}/matches/{auction_id}

Dismiss an auction offer from a request.

**Scope:** `vehiclescan`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `request_id` | URL path | integer | yes | `5` | /api/vehiclescan/requests -> requests[].id | The request id. |
| `auction_id` | URL path | integer | yes | `11409652` | /api/vehiclescan/requests/{request_id}/matches -> offers[].auction_id | The auction to dismiss. |

### Example requests

```http
DELETE https://api.thecarapi.com/api/vehiclescan/requests/5/matches/11409652
```

### Example response

```json
{
  "success": true
}
```

## DELETE /api/vehiclescan/requests/{request_id}/retail/{reference_id}

Dismiss a classifieds offer from a request.

**Scope:** `vehiclescan`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `request_id` | URL path | integer | yes | `5` | /api/vehiclescan/requests -> requests[].id | The request id. |
| `reference_id` | URL path | string | yes | `tp-91744022` | /api/vehiclescan/requests/{request_id}/matches -> retail[].reference_id | The classified listing to dismiss. |

### Example requests

```http
DELETE https://api.thecarapi.com/api/vehiclescan/requests/5/retail/tp-91744022
```

### Example response

```json
{
  "success": true
}
```