Valuation API
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 and appropriate license attached to it.
To use the API, a Vehicle ID returned from the Vehicle Search API or Vehicle Facet API is required.
Vehicle ID
To retrieve a Vehicle ID, use the Vehicle Search APIs.
Pricing ID
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.
Residual Value prediction API
The Residual Value prediction API uses current market trends to influence the depreciation curve of newer vehicles. The API allows you to influence the outcome of the prediction by either mutating AutoGrab's stored Recommended Retail Price, or by providing your own Retail Value for the car.
Trade & Retail Value prediction API
Example
To perform an example request:
curl -XPOST -H 'ApiKey: {API_KEY}' \
-H "Content-type: application/json" \
-d '{
"region": "au",
"vehicle_id": "{VEHICLE_ID}",
"kms": 30000
}' 'https://api.autograb.com.au/v2/valuations/predict'
You can explore this request further in the API Playground.
Pricing by Registration Plate or VIN
To price a vehicle via the registration plate or VIN, you have two options. You can choose to call the /v2/vehicles/registrations/{REGO} or /v2/vehicles/vins/{VIN} endpoint and then pass the returned vehicle_id to the /v2/valuations/predict endpoint, but to streamline your workflow you may prefer to use the direct registration/vin valuation routes (/v2/valuations/registrations/{REGO} and /v2/valuations/vins/{VIN}.
Pricing Adjustments
Both the Residual Value and Used Value APIs support pricing adjustments. These can be used to retrieve a more accurate price prediction of a vehicle if the AutoGrab price is not already accurate enough.
Recommended Retail Price Adjustment
To adjust AutoGrab's stored Recommended Retail Price you can supply a rrp_adjustment value in the payload which accepts a number — positive or negative.
This is useful when a car is fitted with factory extras, the Price When New can be increased for each of the options to get a better price prediction.
Recommended Retail Price Overwrite
To overwrite AutoGrab's stored Recommended Retail Price with your own, use the rrp_overwrite value in the payload which accepts a number.
Predicted Retail and Trade Price Adjustments
The Pricing Adjustments API (/v2/valuations/adjustments) allows you to configure fixed or precentage adjustments for specific AutoGrab Vehicle IDs.
Per-Vehicle Pricing Adjustments will apply to price predictions that you perform using the same API Key and for the same AutoGrab Vehicle ID.
If you set a Retail Price Adjustment for a vehicle, the trade price will also be affected because the trade price is derrived from the retail price. If you set an adjustment for both the retail price and the trade price, both adjustments will be applied to the trade price while the retail price is only affected by the retail price adjustment.
When you perform a price prediction, you will receive a summary of the price adjustments that were applied, if any.
Predicted Retail/Trade Adjustments do not apply to residual valuations.
Example
Below is an example price pediction payload with predicted trade and retail adjustments applied.
{
"success": true,
"prediction": {
"id": "d028809e-0ef5-42de-9699-8b71fd1aee65",
"vehicle_id": "5631424535199744",
"price": 12347,
"score": 0.81820,
"retail_price": 14847,
"trade_price": 2042.46,
"adjustment": {
"vehicle_id": "5631424535199744",
"enabled": true,
"retail_adjustment": {
"type": "fixed",
"amount": 2500,
"overridden": false
},
"trade_adjustment": {
"type": "percentage",
"amount": 0.2,
"overridden": false
},
"overrides": []
}
}
}
Predicted Retail and Trade Price Overrides
As well as Price Adjustments, you also have the option to override Retail and Trade prices for specific Vehicle IDs where the odometer reading falls within a set range. Price overrides are configured using the Price Override API at /v2/valuations/adjustments/{VEHICLE_ID}/overrides.
If you have configured a retail or trade price override that applies to a price prediction, the overridden price will be returned instead of the AutoGrab valuation. This will bypass any price adjustments that you may have configurd, and the response payload will indicate this with the {overridden: true} flag.
Retail price overrides will impact the predicted trade price in the same way that retail price adjustments impact the trade price - unless you have configured a trade price override. In the case where you have both a trade override and a retail override, the two overridden prices will be returned without any pre-processing (except to calculate condition scores, if applicable - see below).
As with Predicted Retail/Trade Adjustments, price overrides do not apply to residual valuations
Example
Below is an example price prediction paylaod where both price adjustments and price overrides have been configured. In this example, the retail price adjustment has been overridden by the retail price override, and the trade price adjustment has been applied.
{
"success": true,
"prediction": {
"id": "faa847f1-d428-46e1-b2d6-b47a00173d6e",
"vehicle_id": "5631424535199744",
"price": 11697,
"score": 0.81820,
"retail_price": 12000,
"trade_price": 1700,
"adjustment": {
"vehicle_id": "5631424535199744",
"retail_adjustment": {
"type": "fixed",
"amount": 2500,
"overridden": true
},
"trade_adjustment": {
"type": "percentage",
"amount": 0.2,
"overridden": false
},
"overrides": [
{
"id": "1ef42b79-c580-4055-a39b-e5257f81d0d9",
"min_kms": 80000,
"max_kms": 90000,
"trade_price": null,
"retail_price": 12000
}
]
}
}
}
Condition Score
Value a vehicle using an AutoGrab ID without requiring a condition_score, return multiple valuations, one for each allowable condition_score [1-5]
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 reccomended you follow the industry standard in the table below.
| Condition | Condition Score |
|---|---|
| Poor | 1 |
| Fair | 2 |
| Average | 3 |
| Good | 4 |
| Excellent | 5 |
If you would like to show a range to the user highlighting the different prices per condition you should use the /v2/valuations/predict/conditions endpoint which will return an array of conditions and their values.
{
"success": true,
"prediction": {
"id": "d8836090-0558-4137-9d86-9ea9597d023f",
"vehicle_id": "4857499144421376",
"kms": 30000,
"price": 20534,
"retail_price": 20534,
"adjustment": null,
"conditions": [
{
"condition_score": 1,
"trade_price": 11923.8
},
{
"condition_score": 2,
"trade_price": 13627.2
},
{
"condition_score": 3,
"trade_price": 15330.6
},
{
"condition_score": 4,
"trade_price": 16182.3
},
{
"condition_score": 5,
"trade_price": 17034
}
]
}
Upper & Lower Bounds
Example
If you would like to understand the market bounds, the range in which the valuation was made, you can use the bounds feature as v2/valuations/predict?features=bounds when invoking any of the following apis:
| Endpoint | Description |
|---|---|
valuations/predict |
Basic valuation predication |
valuations/predict/conditions |
Prediction using a condition input |
valuations/registrations/{plate_number} |
Valuation on a registration plate |
valuations/VINS/{vin} |
Valuaiton on a VIN |
This will result in the example payload below with the upper and lower fields being included.
{
"success": true,
"prediction": {
"id": "44c26d55-5429-413a-b2fa-590de2cfcd9a",
"vehicle_id": "4857499144421376",
"kms": 30000,
"price": 20534,
"retail_price": 20534,
"trade_price": 11923.8,
"adjustment": null
},
"bounds": {
"retail": {
"lower": 19534,
"upper": 21784
},
"trade": {
"lower": 10923.8,
"upper": 13173.8
}
}
}
Regional Availability
The bounds system is currently only available in Australia, and is in development for New Zealand and Malaysia.