# Vehicle History

## Overview

The Vehicle History API allows you to access historical lead listing data from a variety of used car marketplaces. This API requires authentication and an appropriate license attached to it.

The endpoint can be queried using a range of identifiers. VIN is the most readily matched identifier, you can pass in many identifiers to increase the likelihood of matching to a valid listing. See the table below for a list of all supported identifiers.

| Title              | Parameter           | Example           |
| ------------------ | ------------------- | ----------------- |
| Year               | year                | 2019              |
| Make               | make                | Volkswagen        |
| Model              | model               | Polo              |
| Registration Plate | registration\_plate | BMT038            |
| Vin                | VIN                 | KL3TA48E9CB053071 |

#### Example

For example, if you were to use all available identifiers your request would resemble the request below.

{% code overflow="wrap" %}

```json
/v2/sourcing/history?region=nz&registration_plate=BMT038&year=2019&make=Volkswagen&features=price_changes&model=Polo&vin=KL3TA48E9CB053071
```

{% endcode %}

If that vehicle is found, all its relevant events will be included in the response, an example is below.

```json
{
  "success": true,
  "id": "dfe4d117-74e1-4545-9e79-a0baac8208a7",
  "events": [
    {
      "type": "listing",
      "odometer": 100000,
      "price": 100000,
      "marketplace": "Gumtree",
      "timestamp": "2022-09-20T10:22:07.072",
      "seller_type": "string"
    }
  ]
}
```

## Vehicle History Events

The Vehicle History endpoint delivers detailed information on events related to a listing. The following events are possible on a given listing.

**Listing** - the detection of a listing being added to its relevant marketplace.

```json
  {
      "type": "listing",
      "odometer": 100000,
      "price": 100000,
      "marketplace": "Gumtree",
      "timestamp": "2022-09-20T10:22:07.072",
      "seller_type": "string"
    }
```

**Delisting** - the detection of a listing being removed from its relevant marketplace, this is frequently and reliably related to a sale of the vehicle.

```json
  {
      "type": "delisting",
      "odometer": 100000,
      "price": 100000,
      "marketplace": "Gumtree",
      "timestamp": "2022-09-20T10:22:07.072",
      "seller_type": "string"
    }
```

**Price Change** - the detection of a movement in the price, see the features section below for more information.

## Example

To perform an example request:

```bash
curl '/v2/sourcing/history?region=nz&vin=KL3TA48E9CB053071' \
      -H 'ApiKey: {API_KEY}'
```

An example payload is included below to illustrate a potential response.

```json
{
  "success": true,
  "id": "dfe4d117-74e1-4545-9e79-a0baac8208a7",
  "events": [
    {
      "type": "listing",
      "odometer": 100000,
      "price": 100000,
      "marketplace": "Gumtree",
      "timestamp": "2022-09-20T10:22:07.072",
      "seller_type": "string"
    }
  ]
}
```

#### Features

You can opt to enrich to your vehicle history payload by passing in a feature or features separated by commas.

```bash
curl '/v2/sourcing/history?region=nz&registration_plate=BMT038&year=2019&make=Volkswagen&features=price_changes&model=Polo&vin=KL3TA48E9CB053071'
      -H 'ApiKey: {API_KEY}'
```

**Price Changes**

Currently, we support the `price_changes` feature that will show you fluctuations in the price. Passing this feature will return upward on downward movements in the listings' price.

Contact your sales rep to understand your commercial rate card for each feature.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devhub.autotek.my/vehicle-data/vehicle-history.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.