Overview

Our API uses the OpenAPI 2.0 specification, making it easy for our partners to integrate. We want to ensure the best possible experience when integrating with our stack.

Environments

Regions

Certain API endpoints require that a region be passed as part of the request URL. Where necessary it is expected that region=nz be included where region is required.

For example: https://api.autograb.com.au/v2/vehicle/239c8928fnc934fc?region=nz

Region

API Keys

Your account manager will provision API keys for your account. If you require a key to be revoked please get in touch with your account manager.

Quota Limits

APIs have soft quota limits that are enforced based on your contract agreement. To discuss these limits please get in touch with your account manager.

Rate Limiting

We strictly monitor the number of requests per second — if you exceed your allocation the API will respond with HTTP 429 Too Many Requests. We will also return additional headers to help you better understand when rate limits will be applied.

The limits are applied per API product and are decided based on your contract agreement. Rate limits do not relate to quotas.

You can use our test cases to confirm your implementation on our production endpoints. All requests using these values are not billable.

Test Cases

Refer below to set of test cases. They are all linked and refer back to the same vehicle IDs.

Supported Endpoints

Test cases are supported across a range of API endpoints listed below. If the endpoint you are testing with is not listed get in touch to request test data.

• /valuations/predict

• /valuations/vins

• /valuations/registrations

• /valuations/residual

• /valuations/predict/conditions

• /sourcing/market_overlay

• /sourcing/market_overlay/statistics

Implementation Guide

An example implementation could run a test as part of an integration test or development process. For example, you could test a valuation flow by first using a registration plate to get the ID (which is also test data) and send that to a /predict to get a valuation and a market overlay.

The Vehicle Search API allows you to search for matching vehicles by plain-text input. The API will return an array of vehicles and the confidence score in a match for that given vehicle.

The request requires a region, search string & API key. The default page length is 10, however, you can adjust this based on your requirements.

Example

Example Payload

Get vehicle details from a VIN.

The Vehicle VIN API allows you to search for vehicles by VIN. The request requires only a region, VIN & API key. This will return either a matching vehicle with possible option packs, or a null.

Example

curl "https://api.autograb.com.au/v2/vehicles/vins/WVWZZZ6RZAU020000?region=nz" \
     -H 'ApiKey: {API_KEY}'

Example Response

{
    "success": true,
    "vehicle": {
        "id": "5233518187642880",
        "region": "nz",
        "title": "2010 Volkswagen Polo Comfortline Automatic",
        "year": "2010",
        "make": "Volkswagen",
        "model": "Polo",
        "badge": "Comfortline",
        "series": "6R",
        "model_year": "MY10",
        "release_month": 1,
        "release_year": 2010,
        "body_type": "Hatchback",
        "body_config": null,
        "transmission": "Dual Clutch Automatic (DCT)",
        "transmission_type": "Automatic",
        "wheelbase": null,
        "wheelbase_type": null,
        "fuel": "Petrol",
        "fuel_type": "Petrol",
        "engine": "Piston",
        "engine_type": "Piston",
        "drive": "FWD",
        "drive_type": "Front Wheel Drive",
        "num_doors": 5,
        "num_seats": 5,
        "num_gears": 7,
        "num_cylinders": 4,
        "capacity_cc": 1390,
        "power_kw": 63,
        "torque_nm": 132,
        "range": null,
        "options": []
    },
    "upstream_vehicle": "2010 Volkswagen POLO Polo Hatchback Automatic Petrol 1,380cc",
    "confidence": "standard",
    "additional_vehicles": []
}

Remember you can enrich your VIN payloads with features, read about them here.

Key Types

Secret API Key

A secret API key is for the server side and should not be shared with the front end.

Example Key: sec_23hcfb8374bfhc833i4uhx

Public API Key

A public API key is used on your website to call the API. These keys are limited to your domain and are safe to share publicly.

Example Key: pub_3ficuhb34u8fnxu34h9fm

Authenticating Requests

When making requests to the APIs, include the key in your request.

Authorization: ApiKey {your API key}

Other Authentication Methods

We also support OAuth, you can read more about this authentication mechanism here.

At the customer's preference, it is possible to integrate with our APIs via OAuth client credential token grant.

OAuth integration consists of 2 basic components:

1. Token management (ensure your system always has a valid OAuth token available)

2. REST API call signing using a valid token

Token management

Before implementing token management, make sure you have a valid client_id and client_secret as provided by us (Your sales rep will provide them). These are the credentials you will use to get valid tokens from the auth-broker.

auth-broker POST call to receive a valid OAuth token

POST https://api.autograb.com.au/auth-broker/request-token

Post body
{ grant_type: client_credentials }
Headers 
Content-Type: application/x-www-form-urlencoded
Authorization
Basic Auth of form client_id:client_secret Base64 encoded

Sample success response body
{
    "access_token": "[obfuscated-token-string]",
    "expires_in": 3599,
    "scope": "",
    "token_type": "bearer"
}

A valid token can be stored locally for use in subsequent API calls. It is recommended to calculate a safe expiry timestamp based on the expires_in property of the response body and use this to pre-emptively refresh your token when it nears expiry.

REST API call signing

With a valid OAuth token, each REST API call that you make can be authorised by encoding the as-provided token string into your Authorization header using the Bearer prefix.

Troubleshooting

Token management

• I don’t get a 200 response on my request-token calls Double-check your client_id and client_secret with AutoGrab. Double-check your Basic Auth encoding. Double-check your content-type header and post-body structure.

• I have a valid token but my API calls are failing 401 response -- there may be a problem with your token, or the way Bearer Auth is being encoded in the headers.

Overview

The Vehicle Registration API allows you to search for a vehicle by supplying its number plate. The request requires a region, the state (dependent on region), number plate & API key. This will return either a matching vehicle with possible option packs, or a null.

In all cases, and importantly if a matching vehicle is unable to be identified, we will return the upstream_vehicle field allowing you to identify how the relevant road transport authority describes the vehicle. Depending on your use case you may wish to allow front-end users to manually classify the vehicle using the upstream_vehicle as a guide to fill out a Facet-style search.

curl "https://api.autograb.com.au/v2/vehicles/registrations/{number_plate}?region=nz"
-H 'ApiKey: {API_KEY}'

That would produce the payload below.

{
    "success": true,
    "vehicle": {
        "id": "5233518187642880",
        "region": "nz",
        "title": "2010 Volkswagen Polo Comfortline Automatic",
        "year": "2010",
        "make": "Volkswagen",
        "model": "Polo",
        "badge": "Comfortline",
        "series": "6R",
        "model_year": "MY10",
        "release_month": 1,
        "release_year": 2010,
        "body_type": "Hatchback",
        "body_config": null,
        "transmission": "Dual Clutch Automatic (DCT)",
        "transmission_type": "Automatic",
        "wheelbase": null,
        "wheelbase_type": null,
        "fuel": "Petrol",
        "fuel_type": "Petrol",
        "engine": "Piston",
        "engine_type": "Piston",
        "drive": "FWD",
        "drive_type": "Front Wheel Drive",
        "num_doors": 5,
        "num_seats": 5,
        "num_gears": 7,
        "num_cylinders": 4,
        "capacity_cc": 1390,
        "power_kw": 63,
        "torque_nm": 132,
        "range": null,
        "options": []
    },
    "upstream_vehicle": "2010 Volkswagen POLO Polo Automatic Petrol Hatchback 1,380cc",
    "vin": "WVWZZZ6RZAU020000",
    "colour": "SILVER",
    "confidence": "standard",
    "additional_vehicles": []
}

Components

Success - this denotes the outcome of the lookup, if this is not true there are several possible reasons. The plate does not exist, was entered incorrectly or the registration authority could be experiencing an outage (refer to our status page).

Vehicle - this is the array that holds the vehicle data as a result of our matching operation. If Vehicle:Null then we have not been able to identify a matching vehicle. If this is powering a front end UX, you should prompt the user to search via Facets Search to resolve to an vehicle ID. You can use the Upstream_Vehicle below as a UI guide.

Upstream_Vehicle - this is what the Registration Authority has told us the vehicle is. We use this input to match our catalogue.

ID - this is the platform ID of the vehicle, your gateway to leveraging this vehicle in future Valuation, Vehicle Data and more requests.

Summary Data - you will find basic information about the vehicle that you can use to power your UX. If you require more information that is in the Vehicle array consider usage of Vehicle Data endpoints.

Options - these are fittable (not fitted) options available on this vehicle. If you require fitted (from factory data) use the Options Data endpoint.

Confidence - this is the prediction confidence of the match. There are two types of output for this parameter (Standard and degraded).

Additional Vehicle - if there are additional lower confidence matches we will show them to you here.

Features

You can pass in features to request additional data to be sent in the response. Refer to the Features section for more information.

Prefer More Results

This feature will show you additional results at lower-quality matches. Only use this if you would like to see other vehicles that are not likely to be the one you are requesting. Use headerprefer_more_results=true to request this response.

Let's work backwards from the end result which is one or a few results for your user to pick from driven by previous drop-down. There are a few ways to make facets work for you, we'll go through the most common integration method.

Form your GET request for makes

/v2/vehicles/facets?region=nz&facet=make

{
    "success": true,
    "make": [
        {
            "value": "Abarth",
            "count": 47
        },
        {
            "value": "Acura",
            "count": 1
        },
        {
            "value": "Alfa Romeo",
            "count": 713
        },
        {
            "value": "AM General",
            "count": 2
        },
        {
            "value": "Aston Martin",
            "count": 169
// trimmed - this would show all makes in the NZ region

Ask your user to choose a make from the list then call all available models based on that selection. Let's say your user chose Toyota.

Form your request for a list of Models

/v2/vehicles/facets?region=nz&make=Toyota&facet=model

{
    "success": true,
    "model": [
        {
            "value": "4Runner",
            "count": 41
        },
        {
            "value": "86",
            "count": 72
        },
        {
            "value": "Allex",
            "count": 26
  // trimmed - this would show all models in the NZ region

Ask your user to choose a Model from the list then call all available models based on that selection. Let's say your user chose Corolla.

Form your request for a list of badges

v2/vehicles/facets?model=Corolla&region=nz&make=Toyota&facet=badge

{
    "success": true,
    "badge": [
        {
            "value": "SE Ltd",
            "count": 6
        },
        {
            "value": "SE LTD",
            "count": 2
        },
        {
            "value": "Sprint",
            "count": 3
        },
        {
            "value": "Sprinter",
            "count": 5
        },
        {
            "value": "Sprinter SR",
            "count": 1
        },
        {
            "value": "SR",
            "count": 4
        },
 // trimmed - this would show all badges in the NZ region

Select A Badge A Load Vehicles From A Search

Ask your user to choose a badge from the list. Let's say your user chose Sprint. You can see the count is 3, meaning there are only 2 badges. You could send that directly to them or repeat the process with the year (&facet=year) to refine it further.

Let's say you'd like to present the three options to the user.

/v2/vehicles/facets/search?region=nz&badge=Sprint&make=Toyota&model=Corolla

{
    "success": true,
    "vehicles": [
        {
            "id": "5364630897557504",
            "region": "nz",
            "title": "1997 Toyota Corolla Sprint Manual",
            "year": "1997",
            "make": "Toyota",
            "model": "Corolla",
            "badge": "Sprint",
            "series": null,
            "model_year": null,
            "release_month": 9,
            "release_year": 1995,
            "body_type": "Hatchback",
            "body_config": null,
            "transmission": "Manual",
            "transmission_type": "Manual",
            "wheelbase": null,
            "wheelbase_type": null,
            "fuel": "Petrol",
            "fuel_type": "Petrol",
            "engine": "Piston",
            "engine_type": "Piston",
            "drive": "FWD",
            "drive_type": "Front Wheel Drive",
            "num_doors": 5,
            "num_seats": 5,
            "num_gears": 5,
            "num_cylinders": 4,
            "capacity_cc": 1587,
            "power_kw": null,
            "torque_nm": null,
            "range": null,
            "options": []
        },
        {
            "id": "6033133967245312",
            "region": "nz",
            "title": "1999 Toyota Corolla Sprint Manual",
            "year": "1999",
            "make": "Toyota",
            "model": "Corolla",
            "badge": "Sprint",
            "series": null,
            "model_year": null,
            "release_month": 9,
            "release_year": 1995,
            "body_type": "Hatchback",
            "body_config": null,
            "transmission": "Manual",
            "transmission_type": "Manual",
            "wheelbase": null,
            "wheelbase_type": null,
            "fuel": "Petrol",
            "fuel_type": "Petrol",
            "engine": "Piston",
            "engine_type": "Piston",
            "drive": "FWD",
            "drive_type": "Front Wheel Drive",
            "num_doors": 5,
            "num_seats": 5,
            "num_gears": 5,
            "num_cylinders": 4,
            "capacity_cc": 1587,
            "power_kw": null,
            "torque_nm": null,
            "range": null,
            "options": []
        },
        {
            "id": "6563011892346880",
            "region": "nz",
            "title": "1998 Toyota Corolla Sprint Manual",
            "year": "1998",
            "make": "Toyota",
            "model": "Corolla",
            "badge": "Sprint",
            "series": null,
            "model_year": null,
            "release_month": 9,
            "release_year": 1995,
            "body_type": "Hatchback",
            "body_config": null,
            "transmission": "Manual",
            "transmission_type": "Manual",
            "wheelbase": null,
            "wheelbase_type": null,
            "fuel": "Petrol",
            "fuel_type": "Petrol",
            "engine": "Piston",
            "engine_type": "Piston",
            "drive": "FWD",
            "drive_type": "Front Wheel Drive",
            "num_doors": 5,
            "num_seats": 5,
            "num_gears": 5,
            "num_cylinders": 4,
            "capacity_cc": 1587,
            "power_kw": null,
            "torque_nm": null,
            "range": null,
            "options": []
        }
    ],
    "total": 3
}

If you do not pay attention to the counts under each facet there may be to many vehicle to perform a search on. You will know you have triggered this limitation if you see the error below.

{
    "error": true,
    "message": "Too many vehicles, you must return at least make, model, badge, series, year"
}

Search for Vehicles by facets

The Vehicle Facets API allows you to narrow down the matching vehicle based on the vehicle's parameters. The facets available are: year, make, model, badge, series, transmission, body, body_style, fuel, engine and wheelbase.

If you would like to return aggregations of factes, use a comma-separated list in the facets field: eg. facets=badge,series,transmission.

Facets User Interface Example

This function is useful when supplying data to drop-downs for display on a form. A good example of using Facets API is Westside Auto.

For a preview of how facets in implemented inside the AutoGrab web app see the video below.

The Sourcing API set allows you to find listing data for comparative and market insights. This API requires and an appropriate license attached to it.

If you know a vehicles ID already and would like summary data you can leverage a basic vehicle search.

Request

v2/vehicles/5233518187642880?region=nz

Response

The Sourcing API allows you to access lead and listing data from a variety of used car marketplaces.

This API requires and an appropriate license attached to it.

Market Overlay API

When viewing a lead on the web app, a view of similar leads that are currently listed for sale or recently sold is available on the side of the page (the 'Market Overlay'). The Market Overlay API gives you programmatic access to this data, enabling you to show price justifications or re-create our market comparison view for your own purposes.

To access a Market Overlay, you will need to specify a Vehicle ID to search for relevant listings. To retrieve a Vehicle ID, use any of the .

When retrieving market data for a Vehicle ID, a best-effort attempt is made to find at least four listings. This search begins by looking at the latest 60 days, and if there is not enough data in this time period, another 10 days of data is added until the minimum quota of four is reached.

If you would like a larger sample of market data, you can specify a minimum_days value and this will override the default minimum of 60 days.

Example

To perform an example request:

An example payload is included below, although only the first lead is shown to save space:

Request Parameters

The market overlay can be enhanced by passing option feature parameters. You can request a single feature or combine them to enrich your responses. You must have a unique permission enabled by your sales representative for each feature.

Dealer Contact Details

This feature will deliver the contact details of the advertising dealership as per the listing. Use features=dealer_contact_details

Lead Starting Price

This feature will deliver the initial price the lead was advertised at. Use features=lead_starting_price

Lead Price Drops

This feature will deliver the count of times the price has been dropped. If you would like to know what each drop (or increase) was consider the endpoint. Use features=lead_price_drops

Vehicle RRP

This feature will deliver the RRP of the vehicle when it was new according to our vehicle data catalogue, the same data and more is available via our . Use features=vehicle_rrp

All Listing URLs

This feature will deliver the listing URLs related to the lead across all sites it is listed on. Use features=listing_urls

Primary Cover Image

This feature will deliver the cover image for each record where available. Each image is stored for 90 days after delisting. Use features=cover_image

All Images

This feature will deliver all primary images for each record where available. Each image is stored for 90 days after delisting. Use features=all_images

Primary Listing Description

This feature will deliver the primary listing description for each record where available. Use features=primary_description

Registration Plate

This feature will deliver the vehicle's registration plate in the market overlay payload. Use features=rego

VIN

This feature will deliver the vehicle's VIN in the market overlay payload. Use features=VIN

Stock Number

This feature will deliver the vehicle's stock number in the market overlay payload. Use features=stock_no

The matcher is a foundational piece of technology that reconciles market, listing and data inputs describing cars against our vehicle catalogue. This is done so you can utilise our market-leading vehicle ID for additional workflows like valuation, market data and more.

For example, when you request information on a registration plate the primary input we receive is its description "upstream_vehicle": "2019 Isuzu Ute MU-X 4x2 LS-M 4 Wagon 6sp auto 3.0L 3000cc 4cyl T/Diesel 2018. That needs to be matched to "id": "4843865643155456" which represents hundreds of data points related to the Isuzu.

We are transparent about the confidence of the match and you can leverage this to inform your workflows. In each relevant vehicle discovery method you will receive a "confidence" response.

In the reduced confidence outcome we highly recommend showing the upstream_vehicle parameter. This will help your user ensure the vehicle we have responded with is representative of the real vehicle.

Overview

In a scenario where you want to understand the vehicle ID or data on listed vehicles, you can use the marketplace search system.

Prerequisites to access:

1. To be approved to access this special use case endpoint, contact your account manager.

2. Be aware of your listing ID and use that for the marketplace_id parameter.

3. Be aware of your marketplace identifier, it is your public domain name, e.g drive.com.au

Example Usage

For example, if you were AutoTrader located in NZ with listing 808159 you could form the request below.

You will get this response with the vehicle ID "4969003601429068" allowing you to interact with other services like the , and more.

Limitations

You are only able to search for a vehicle once it is present on our service. If you receive the error below this means we are not yet aware of the listing due to its recency.

Overview

The Market Overlay Statistics API delivers statistics we generate on your behalf from the Market Overlay endpoint.

Starting with your Vehicle ID post it to the statistics endpoint.

v2/sourcing/market_overlay/statistics/5655899674771456&minimum_days=60&region=nz

An example response is below.

{
    "success": true,
    "sample_size": 282,
    "days_checked": 60,
    "outlier_count": 9,
    "avg_days_to_sell": 14.310300431547615,
    "price_when_new": 56390
}

As this endpoint is part of the market overlay route you can enhance your payload with additional features. Refer to the features on the market overlay to see what's available.

Overview

To request an extensive factory build data list call the /build-data endpoint. If the relevant manufacturer is participating in our Options data product you will see it in the response.

For example, you could request build information VIN:WVWZZZAWZKU065305 as below.

/v2/vehicles/vins/SALWA2KE5EA312255/build-data?region=nz

The VIN decodes to a Volkswagen Polo, as VW is participating in the Build data program we are able to deliver the following build data.

{
    "success": true,
    "vehicle": {
        "vin": "WVWZZZAWZKU065305",
        "build_date": "2019-03-19",
        "make": "VOLKSWAGEN",
        "model": "POLO",
        "features": [
            {
                "code": "00A",
                "value": "Rear overhang, short"
            },
            {
                "code": "0A2",
                "value": "4 doors"
            },
            {
                "code": "0AR",
                "value": "Front stabilizer bar"
            },
            {
                "code": "0B1",
                "value": "Wheelbase"
            },
            {
                "code": "0EG",
                "value": "Dual-clutch transmission DSG DQ200"
            },
            {
                "code": "0FV",
                "value": "South Africa manufacturing sequence"
            },
            {
                "code": "0K0",
                "value": "Without alternative drive system"
            }

        ]
    }
}
```

If we are unable to provide build information for the requested VIN we will return an error like this.

{
    "error": true,
    "message": "Invalid or Unsupported VIN"
}

If you are not using a valid VIN we will respond with this.

{
    "error": true,
    "message": "Invalid VIN, must be 17 characters."
}

Coverage

The Factory build data program covers most major manufacturers back to vehicles built in 1999. Contact us to request if we have coverage of a specific area.

As of 2023 the system has coverage across 40 manufacturers as below:

• Abarth

• Alfa Romeo

• Alpina

• Audi

• Bentley

• BMW

• Buick

• Cadillac

• Chevrolet

• Chrysler

• Citroën

• Dacia

• Daewoo

• Dodge

• DS

• Fiat

• Ford

• GMC

• Hummer

• Hyundai

• Isuzu

• Jaguar

• Jeep

• KIA

• Lancia

• Land Rover

• Lincoln

• Maybach

• Mercedes-Benz

• MINI

• Opel

• Porsche

• Peugeot

• Renault

• Rolls-Royce

• Saab

• SEAT

• Skoda

• smart

• Vauxhall

• Volkswagen

• Volvo

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.

Example

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

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

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

{
  "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.

  {
      "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.

  {
      "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:

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

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

{
  "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.

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.

The Vehicle Data API set allows you to find descriptive information on a vehicle at the level of granularity you require. This API requires authentication and an appropriate license attached to it.

The Valuation API set allows you to predict current and future prices on vehicles. This API requires authentication and an appropriate license attached to it.

The Vehicle Search API set allows you to find matching vehicles within our database. This API requires authentication and an appropriate license attached to it.

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 provided price is not already accurate enough.

Recommended Retail Price Adjustment

To adjust the 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 the systems 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 percentage adjustments for specific Vehicle IDs.

Per-vehicle pricing adjustments will apply to price predictions that you perform using the same API Key and for the same Vehicle ID.

If you set a Retail Price Adjustment for a vehicle, the trade price will also be affected because the trade price is derived 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 prediction payload with predicted trade and retail adjustments applied.

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 configured, 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 payload 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.

Valuation Bounds

If you require the upper and lower bounds used to calculate a prediction you can use features=bounds.

This will yield the bounds on the retail and trade prices.

/v2/valuations/registrations/BMT038?features=bounds

Max Offer Adjustments

If you have a max offer profile setup via API or via the AutoGrab web app you can opt to receive the same results via API. Use features=max_offer to receive them in your response.

/v2/valuations/predict?features=max_offer

You can request more data than the standard payload by leveraging a range of features described below.

Max Offer - Retail Base

This feature will return your max configuration in your valuation with the final price showing the deductions from the retail valuation. Use features=max_offer to receive this payload. Read more on how to set and update your .

Max Offer - Trade Base

This feature will return your max configuration in your valuation with the final price showing the deductions from the trade valuation. Use both features=max_offer_trade,max_offer to receive this payload. Read more on how to set and update your .

Bounds

This feature will return the upper and lower bounds used as part of your valuation. Use features=bounds to receive this payload.

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 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

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

Payload

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.

Condition Score

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.

Registration Valuation

POST the registration plate and region to /v2/valuations/registrations/BMT038?

Example Response

VIN Valuation

POST the encapsulated VIN to /v2/valuations/vins/7AT08G0RX19303899

Example Response

Implementation Constrains

This integration approach relies on the successful lookup of the vehicle. We recommend staggering your integration so you isolate the vehicle ID first using vehicle search methods and then proceed to valuation driven by the vehicle ID.

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 stored Recommended Retail Price or by providing your own Retail Value for the car.

In the example below we are sending the vehicle ID along with other key details to /v2/valuations/residual. The example body of the post is below.

This yields a prediction over the 5-year projection timeframe as below.

If you wish to predict valuations at all available conditions of the vehicle. That is those between 1 and 5,with 1 being poor and 5 being excellent condition. You can utilise the conditions in the same way you would use the standard /v2/valuations/predict/ endpoint.

In this endpoint, we will return all available conditions in an array. This can power great user experiences where you may wish to show a large range depending on the condition of the vehicle.