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

The AutoGrab AutoGauge is an iFrame widget that displays a valuation as well as some high-level market data for a vehicle listing. We host a configuration file that controls a range of labelling and styling variables that we will guide you through as part of your integration.

Query Parameters

Since the gauge operates in an iFrame, it is controlled using query parameters. These parameters are separated into two distinct groups: Base parameters and vehicle-type parameters. The base parameters are applicable for all use cases, whereas you only need to choose one set of vehicle-type parameters in order to use the gauge.

Base parameters

api_key: string; Your Gauge API Key (locked to your provided domains).

region: Region; The country code (‘au’, ‘nz’, 'uk', or ‘my’)

odometer: number; The odometer reading for the vehicle you are valuing

listing_price: number; The listing price for the vehicle you are valuing

layout?: string; The desired layout style (‘horizontal’ or vertical). If a layout type is not provided, this will default to ‘vertical’.

These parameters are used to determine the type of vehicle that you are valuing, and only one of these sets of properties are required to match a vehicle. Depending on your use case, it may be easier to use certain sets of parameters over others.

vehicle_id The AutoGrab vehicle ID

marketplace and marketplace_id The marketplace domain name where the vehicle is publicly listed (e.g. ‘carsales.com.au’) and the unique listing ID on the marketplace (e.g. ‘OAG-AD-216621’)

vin The vehicle's VIN number

rego The registration plate (e.g. ‘BMT038’).

vehicle_description The plain text vehicle description (e.g. ‘2019 Volkswagen Polo 85TSI Comfortline Auto MY19’)

With VIN

With Rego & State

With Marketplace/Marketplace ID

With Vehicle Description

To test the gauge locally, simply create an index.html file with the following contents:

You can then host this file on localhost:8080 using the npx-server package. You can use the ‘npx’ command line tool to do this:

> npx html-server ./index.html

The localhost:8080 URL is whitelisted for your API key, therefore enabling this workflow.

If the Gauge is successfully rendered, we send a message via the iframe postMessage function. The way for a client to listen for the event is as follows:

There is no minimum valuation threshold set per API key. We can configure this to your requirements.

The Recall Check API allows you to access the current recall status of a given vehicle based on the registration. This API requires authentication and an appropriate license attached to it.

Overview

The widget can capture leads by auto-filling vehicle information, asking key questions and making a conditional offer informed by your preset valuation strategy.

It is highly customisable to your dealership brand or corporate imagery requirements, feeling at home on your existing website.

The resulting leads are deployed over email or select LMS providers depending on your region.

Example Implementations

You can find an example of the valuation widget operating on the AutoGrab corporate homepage here. For a more brand / corporate imagery-compliant implementation refer to Berwick Motor Group.

Implementation

Speak to your sales rep about your desired implementation pattern. We will supply you with staging and production iFrame url code as part of your deployment process.

Position On Page

You have two options to embed the iframe inside your website. In both these options, it is critical that you set the iframe width to 650px and centred.

Popup - holding the iframe in a popup container and ensuring you conform to the AUTOGRAB_VALUATION_HIDE to event listening to close the popup container and AUTOGRAB_VALUATION_DIMENSIONS resize the height dynamically.

On Page - holding the iframe on a page ensuring you let us know so we can remove the close button. Since the page can still extend vertically you need to respond to the AUTOGRAB_VALUATION_DIMENSIONS alert.

The valuation widget will send messages you need to pay attention to via the iframe postMessage function. The messages are as follows.

AUTOGRAB_VALUATION_SUCCESS

The widget loaded successfully, no intervention is needed.

AUTOGRAB_VALUATION_ERROR

There was an exception or error delivering the iframe contents.

AUTOGRAB_VALUATION_HIDE

The close button at the end of the workflow or close X in the interface has been pressed.

AUTOGRAB_VALUATION_DIMENSIONS

The iframe has resized due to changed in the contents. Please respond by resizing the iframe container to hold the new contents without cropping.

Overview

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

Prerequisites to access.

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

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.

In this scenario, we recommend falling back to a test lookup using the title in its most descriptive format. E.g 2024 Nissan X-TRAIL Ti Wagon Ti 2.5L SUV 4WD.

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

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

This feature will return structured descriptive data from the registration authority. Use features=additional_upstream_data to receive this payload.

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.

Requests to our APIs must include an ApiKey header for authentication.

Include your API key in the request headers as shown in the example below.

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

To deliver a PAV-style experience you can leverage existing API endpoints to deliver your desired UX. Below is a broad guide on how to achieve a similar outcome. Each integration will have nuances and specific commercial differences - don't hesitate to speak to your Integrations support person or sales executive for guidance.

Workflow Overview

Isolate The Vehicle ID

To begin the journey you will need to convert a real-world identifier into a vehicle ID to progress through the wider set of data. You can do this in four common ways;

1. Registration Plate Search - the most common identifier consumers and agents are familiar with.

2. - for unregistered or for scenarios where a plate is not known

3. - for scenarios where a standard identifier is not known or where the data delivered from upstream (Road Authority) is not reliable.

For example, the response from a Registration search is below. Importantly you want to identify the ID, "id": "5932950835167232" for use in future steps.

We offer a range of data enrichment packs to deliver more information in your registration or VIN lookups, . Consider the usage of the compliance information or vehicle age products.

To understand the position of that vehicle in the market you would call on the y service. This would deliver you a large payload of information on the competitive set of the vehicle.

To enrich your Overlay information we suggest employing additional features. For this use case, those are

1. - to get all the images attached to the lead inside AutoGrab.

2. - to get the primary detailed description of each listing for UI display purposes.

To understand the value of the vehicle you will want to run a Valuation using the endpoint. That will give you the current retail and trade values for the vehicle. Consider employing the to understand the valuation upper and lower thresholds as part of this calculation.

AutoGrab can service PDF reports over API that can then be handled in your application.

The report endpoint has the ability to determine the content of the report based on the information that is handed to it.

Where-ever possible it is recommended to provide as much vehicle information as possible. What the data is used for is controlled by the sources array.

• VIN

• Registration/State - If registration is provided, state is mandatory

• Odometer

OAuth will only work for agreed AutoGrab api_v2 REST endpoints where an ApiKey has already been provisioned.

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 AutoGrab. (They will be provided by your sales rep.) These are the credentials you will use to get valid tokens from the AutoGrab auth-broker.

auth-broker POST call to receive a valid OAuth token

Copy

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.

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

Troubleshooting

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

AutoGrab hosts a range a embeddable products you can use to rapidly deploy solutions to the market to engage new customers and delight existing ones.

Overview

The MOT & Tax Search API allows you to obtain the current MOT and Tax status of a given vehicle based on its registration.

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

The AutoGrab AutoGauge is an endpoint that delivers market benchmarking information with inputs of listing information. It supports a range of inputs depending on your use case.

The body of the request can accept a range of inputs depending on your listing data. All available inputs are below.

The response for this request is below. The AutoGauge can be presented with a broad range of vehicle identifiers and will consider them dependent on your commercial agreement. In the scenario above, the AutoGrab ID was presented and used, and all other inputs were supplied as backups.

If you are a marketplace you will store your own marketplace IDs against each listing. You can submit those via the request body to produce an AutoGauge response.

As a customer with an existing AutoGrab API integration, you will likely have stored the AutoGrab IDs from vehicle search steps you've previously taken. In this case supply your known vehicle_id as part of the request. This is the lowest-cost implementation as it does not require a VIN or Registration search.

As an app or new customer, you may only have the VIN and registration information for your vehicles. You can pass them into the request body as below.

The Vehicle Data API set allows you to find descriptive information on a vehicle at the level of granularity you require. 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.

You can explore our endpoints by searching or asking questions through the AI-powered doc system. See what product fits your user case by clicking a top-level grouping below.

You can use our test cases to confirm your implementation on our production endpoints. Requests using these values are not billable: sandbox responses carry sandbox: true and billable: false, and never reach an upstream data provider.

The test cases are all linked. Every plate, VIN and vehicle ID below resolves to the same fake 2019 Toyota Corolla (vehicle ID 1111111111111111, VIN 00000000000000000). The EV cases resolve to a fake 2023 Tesla Model Y (vehicle ID 1111111111111112, VIN 00000000000000010).

Plates are matched case-insensitively and ignore spaces and hyphens, so ZZ99 OKK, zz99okk

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.

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

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

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.

The system has coverage across 40 manufacturers as below:

• Abarth

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.

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

For example: https://api.autograb.co.uk/v2/vehicle/3190324654943863?region=uk