Endpoints

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.

Requires the vehiclescan scope.

Example request

Request

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

Example response

json

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

GET

/api/vehiclescan/options

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

Requires the vehiclescan scope.

Parameters

brandstring · query string

Returns this make’s models instead.

Example BMW·Where the value comes from /api/vehiclescan/options -> makes

countrystring · query string

Narrows the options to one country.

Example DE·Where the value comes from Your user’s market.

Example requests

Request

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

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.

Requires the vehiclescan scope.

Example request

Request

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.

Requires the vehiclescan scope.

Parameters

criteriaobject[] · JSON bodyrequired

1 to 5 vehicles, each with a make.

Example [{"make": "BMW", "model": "320d", "year_from": 2018}]·Where the value comes from /api/vehiclescan/options

Example request

Request

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
}

PUT

/api/vehiclescan/requests/{request_id}

Replace a request’s vehicles.

Requires the vehiclescan scope.

Parameters

request_idinteger · in the URL pathrequired

The request id.

Example 5·Where the value comes from /api/vehiclescan/requests -> requests[].id

criteriaobject[] · JSON bodyrequired

1 to 5 vehicles, each with a make. Matching restarts from the offers listed now.

Example [{"make": "BMW", "model": "330d"}]·Where the value comes from /api/vehiclescan/options

Example request

Request

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.

Requires the vehiclescan scope.

Parameters

request_idinteger · in the URL pathrequired

The request id.

Example 5·Where the value comes from /api/vehiclescan/requests -> requests[].id

Example request

Request

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.

Requires the vehiclescan scope.

Parameters

request_idinteger · in the URL pathrequired

The request id.

Example 5·Where the value comes from /api/vehiclescan/requests -> requests[].id

activeboolean · JSON bodyrequired

false pauses matching, true resumes it.

Example false·Where the value comes from Your choice.

Example request

Request

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.

Requires the vehiclescan scope.

Parameters

request_idinteger · in the URL pathrequired

The request id.

Example 5·Where the value comes from /api/vehiclescan/requests -> requests[].id

Example request

Request

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
}

What you get back

offers / retailobject[]

Auctions and classifieds respectively, up to 200 each. is_new marks offers found since the request was saved; dismissed offers are left out.

limitedboolean

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.

Requires the vehiclescan scope.

Parameters

request_idinteger · in the URL pathrequired

The request id.

Example 5·Where the value comes from /api/vehiclescan/requests -> requests[].id

auction_idinteger · in the URL pathrequired

The auction to dismiss.

Example 11409652·Where the value comes from /api/vehiclescan/requests/{request_id}/matches -> offers[].auction_id

Example request

Request

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.

Requires the vehiclescan scope.

Parameters

request_idinteger · in the URL pathrequired

The request id.

Example 5·Where the value comes from /api/vehiclescan/requests -> requests[].id

reference_idstring · in the URL pathrequired

The classified listing to dismiss.

Example tp-91744022·Where the value comes from /api/vehiclescan/requests/{request_id}/matches -> retail[].reference_id

Example request

Request

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

Example response

json

{
  "success": true
}