# 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 operates on a tiered system of queries:

**VIN** - The first initial call can be made to VIN + Region. However, if VIN does not return any history information, the following data is required as a fallback.

* **Year**
* **Make**
* **Model**
* **Registration**

{% hint style="info" %}
It is recommended to provide all available data points when doing a Vehicle History call, only use VIN if no other data is available.
{% endhint %}

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

{% hint style="warning" %}
The Make, Model fields are format-sensitive and rely on AutoGrabs Vehicle Search or ID lookup formatting. If using unsupported make and model descriptions, the vehicle history will not be returned when otherwise it could have been using the correct formatting.
{% endhint %}

{% openapi src="<https://2006860467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5qLYvzu45gdlTAGQCN9d%2Fuploads%2FQNJ2oRfASYWNsu7VjJHE%2Fapi.yaml?alt=media&token=58a3820d-1bba-4403-8808-4c1bbeab3f41>" path="/v2/sourcing/history" method="get" %}
[api.yaml](https://2006860467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5qLYvzu45gdlTAGQCN9d%2Fuploads%2FQNJ2oRfASYWNsu7VjJHE%2Fapi.yaml?alt=media\&token=58a3820d-1bba-4403-8808-4c1bbeab3f41)
{% endopenapi %}

## Vehicle History Events

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

**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=au&vin=KL3TA48E9CB053071u' \
      -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 your vehicle history payload by passing in a feature or features separated by commas.

```bash
curl '/v2/sourcing/history?region=au&registration_plate=BMT038&state=VIC&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.