# Valuation Predictions

## Overview

The Valuation API can be used to determine the present retail & trade values, as well as the residual values of new vehicles.

This API requires [authentication](https://docs.autograb.com.au/guide/auth/) and an appropriate license attached to it.

To use the API, a Vehicle ID returned from the Vehicle Search API or Vehicle Facet API is required.

## Example

**Request**

{% hint style="info" %}
To retrieve a Vehicle ID, use the [Vehicle Search APIs](https://docs.autograb.com.au/guide/vehicle/).
{% endhint %}

Starting with a vehicle ID post it to /v2/valuations/predict

```json
{
    "region": "nz",
    "vehicle_id": "5804870883868672"
    "kms": 30000,
    "condition_score": 2
}
```

{% hint style="info" %}
The [condition score](#condition-score) is optional and can be used to further refine your pricing prediction.
{% endhint %}

**Payload**

```json
{
    "success": true,
    "prediction": {
        "id": "a2955915-9611-40ef-8b98-b827dad76ff4",
        "vehicle_id": "5804870883868672",
        "kms": 57306,
        "price": 20622,
        "score": 0.9239,
        "retail_price": 20622,
        "trade_price": 17122,
        "adjustment": null
    }
}
```

#### Pricing ID <a href="#pricing-id" id="pricing-id"></a>

The payload returned by price prediction requests will include an ID, which you can use to refer to the pricing request in the future. The `/v2/valuations/history/{PRICING_ID` method will return the response from a previous pricing request, and you can also use the Pricing ID to track price changes with the **Price Changes API**, if licenced.

To get a paginated list of all your previous price predictions, you can use the `/v2/valuations/history` endpoint.

#### Condition Score <a href="#condition-score" id="condition-score"></a>

By supplying a condition score, you can manipulate the `trade_price` returned by the prediction endpoint. The condition score can be between `1` and `5`. A condition of `1` being poor condition and a condition of `5` excellent condition.

Supplying any other numbers will return the default `trade_price` which assumes excellent condition.

If you're building a user interface where you allow the user to choose a condition it is recommended you follow the industry standard in the table below.

<table><thead><tr><th width="162">Condition</th><th>Condition Score</th></tr></thead><tbody><tr><td>Poor</td><td><code>1</code></td></tr><tr><td>Fair</td><td><code>2</code></td></tr><tr><td>Average</td><td><code>3</code></td></tr><tr><td>Good</td><td><code>4</code></td></tr><tr><td>Excellent</td><td><code>5</code></td></tr></tbody></table>