1 of 51

🇳🇿 NZ AutoGrab API Doc

AutoGrab Basics

AutoGrab Developer Hub

Welcome to the developer hub, this is your reference to integrate with all aspects of the system. We've got guides and reference materials to support and accelerate your development.

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.

Integration Overview

Key things to know before you start.

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

Environment

URL

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

Country

Region Code

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.

Header

Example

Description

API Test Cases

Test your requests in a safe zero-cost way through our test case set.

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.

Type

Region

Value

Authentication

Basic Key Based Authentication

We support API key-based authentication, recommended if you build applications to integrate with our platform.

Do you need a key? Contact your sales rep or contact to request one to start developing.

Key Types

OAuth Authentication

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:

Token management (ensure your system always has a valid OAuth token available)
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

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.

Vehicle Search

Plain-text Search

Get results with a text string search

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

/v2/vehicles?region=nz&search=2019 Volkswagen Polo S

Example Payload

VIN Search

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.

Facet Search

Use smart drop downs to find a vehicle.

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 .

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

Marketplace ID Lookup

A special use case endpoint for our marketplace customers to find their own leads on AutoGrab systems.

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:

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

Vehicle ID Search

Get summary data on a vehicle by searching for its ID

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

{
    "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": []
    },
    "success": true
}

Matching Confidence

Understand how we match vehicles and the expected outcomes.

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.

Confidence Parameter

Explanation

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.

Sourcing

Sourcing Basics

Find the right market data to inform your decision making

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.

Features

Enrich your market overlay payloads with additional data.

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

Market Statistics

Get key statistics on any vehicle ID

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.

Vehicle Data

Vehicle Data Basics

Get the level of detail you need on the vehicle you want.

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.

Vehicle History

Request a vehicles history on marketplaces

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.

Title

Parameter

Factory Build Data

Request data the vehicle was fitted with at the factory

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.

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.

Valuation

Valuation Basics

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

Valuation Predictions

Generate market accurate predictions for vehicles.

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.

Condition Array

Predict all potential values across many conditions for a vehicle.

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.

Valuation Features

Generate upper and lower bounds on each valuation.

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

{
    "success": true,
    "prediction": {
        "id": "e2813b16-1012-41b5-9ea3-3b65675c50fd",
        "vehicle_id": "5804870883868672",
        "kms": 57306,
        "price": 20622,
        "score": 0.9239,
        "retail_price": 20622,
        "trade_price": 17122,
        "adjustment": null
    },
    "bounds": {
        "retail": {
            "lower": 19622,
            "upper": 21872
        },
        "trade": {
            "lower": 16122,
            "upper": 18372
        }
    }
}

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

If you want to set or update your .

Residual Valuations

Predict the future value of a vehicle.

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.

{
    "region": "au",
    "vehicle_id": "5804870883868672",
    "initial_kms": 30000,
    "yearly_kms": 20000
}

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

{
    "success": true,
    "predictions": [
        {
            "year": 0,
            "kms": 30000,
            "valuation": 23103,
            "score": 0.818203282
        },
        {
            "year": 1,
            "kms": 50000,
            "valuation": 20601,
            "score": 0.81823397
        },
        {
            "year": 2,
            "kms": 70000,
            "valuation": 18323,
            "score": 0.818168287
        },
        {
            "year": 3,
            "kms": 90000,
            "valuation": 16250,
            "score": 0.818181818
        },
        {
            "year": 4,
            "kms": 110000,
            "valuation": 14365,
            "score": 0.818124288
        },
        {
            "year": 5,
            "kms": 130000,
            "valuation": 12655,
            "score": 0.818175287
        }
    ]
}

Valuation Features

Enhance your requests with additional data.

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

Ensure your commercial agreement has these features enabled if you require them.

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

Max Offer Configuration

Set and update your max offer config to refine your price predictions.

Get Configuration

Get your existing max offer configuration by using the request below.

/v2/valuations/max_offer_configuration

You will receive a payload as per below showing you your current configuration.

{
  "success": true,
  "max_offer_configuration": {
    "reconditioning_percentage": 0,
    "reconditioning_fixed": 0,
    "profit_margin_percentage": 0,
    "profit_margin_fixed": 0,
    "lot_percentage": 0,
    "lot_fixed": 0,
    "transport_percentage": 0,
    "transport_fixed": 0,
    "admin_percentage": 0,
    "admin_fixed": 0
  }
}

Update Configuration

Upsert a max offer configuration to change a part of it.

/v2/valuations/max_offer_configuration

Your PUT request must conform to our schema as outlined below.

{
  "reconditioning": {
    "amount": 1000,
    "type": "fixed"
  },
  "profit_margin": {
    "amount": 1000,
    "type": "fixed"
  },
  "lot": {
    "amount": 1000,
    "type": "fixed"
  },
  "transport": {
    "amount": 1000,
    "type": "fixed"
  },
  "admin": {
    "amount": 1000,
    "type": "fixed"
  }
}

AutoGauge

Create your own price indication and benchmarking gauge.

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.

Example Post Body

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.

Use Case-Driven Implementation Examples

Marketplace Implementation

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.

Dealer Website Implementation (AutoGrab Customer)

As a customer with an existing AutoGrab API integration, you will likely have stored the vehicles 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.

Dealer Website Implementation (Non-Direct Customer)

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.

Registration or VIN-driven AutoGauge requests attract an additional lookup fee. Speak to your account representative for commercial implications.

Embeddable Products

Embeddable Basics

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

Valuation Widget

The Valuation Widget offers an easy-to-configure and install instant cash offer journey for your website.

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. For a more brand / corporate imagery-compliant implementation refer to

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.

Event Listeners

Please ensure your implementation meets the minimum event listener requirements.

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.

Market Insights Snapshot

The Market Insights Snapshot system provides insights into the marketability of a given car in a marketplace.

Overview

The widget can show regionalised market insights based on input vehicles. It is customisable to your brand via a hero brand icon. The resulting market information can help your customers understand the market reception to a given vehicle.

Other Products & Resources

Pre-Accident Valuation API Suite

Deliver you own PAV style product by leveraging a range of AutoGrab API products.

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

URL Linking Structure

Jump directly out of your own applications into a valuable part of the AutoGrab product suit.

As an approved integration partner you can create buttons inside your system that link directly to parts of the AutoGrab product suite. This can create valuable user experiences for your customers giving them new abilities to explore datasets outside your platform.

The "app.autograb.com.au/" prefix applies for most users, consider if your AutoGrab customer audiences use SSO to access the app. If so you may need to dynamically update your prefix like "example.autograb.com.au/".

Brand Guidelines

How to use AutoGrabs brand correctly

The following guidelines help developers to use AutoGrabs’s brand and assets correctly and consistently where approved to do so.

Naming Apps and Integrations

When naming apps and integrations that use AutoGrab data, please follow these guidelines:

Use a unique name for your application or integration

API Reference Parameter

Use this to utilise a single API key but track usage by passing a unique param per use-case or customer.

On any endpoint add the new parameter reference_id and pass in your ID.

This ID will be stored against usage records if supplied and can be used to support custom billing workflows as agreed with your account representative.

FAQ

These are frequently asked questions about AutoGrab and our products.

What is a VIN?

The car's vehicle identification number (VIN) is the identifying code for a specific automobile. The VIN serves as the car's fingerprint, as no two vehicles in operation have the same VIN. A VIN is composed of 17 characters (digits and capital letters) that act as a unique identifier for the vehicle. A VIN displays the car's unique features, specifications and manufacturer. The VIN can be used to track recalls, registrations, warranty claims, thefts and insurance coverage.

What is an Vehicle ID?

An AutoGrab ID or AGID is a unique identifier for a vehicle in our catalogue. All vehicles inside AutoGrab reference this as the source of metadata about the vehicle.

How do I know the current status of each endpoint?

Go to to view the current system state.

Adjustments

Adjust valuations we send you based on a rule set.

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.

AutoGauge

AutoGrabs dynamic pricing indicator for your website

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.

You can access this over API if you would like to make your own implementation over the iFrame, read more here.

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

Vehicle Type Parameters

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

Example Usage

With VIN

With Rego

With Marketplace/Marketplace ID

With Vehicle Description

Local Testing

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.

Event Listeners

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.

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

Customer Recapture

The Customer Recapture API allows you to upload, view and delete Customer Recapture customers.

This API requires authentication and an appropriate license attached to it.

Uploading Customer Lists

The main purpose of the Customer Recapture API is to facilitate the automated upload of new Recapture customers.

Customer lists are often very long, so the Customer Recapture API allows you to queue customer uploads without immediately processing every customer in the list. There is an endpoint to queue the upload, and separate endpoints to check the status of the upload, and cancel it, if necessary.

Upload a list of customers

A POST request to https://api.autograb.com.au/v2/recapture/upload?region=nz will initiate a new queued customer list upload.

The request body has three key parameters:

name: A name to assign to the upload, for personal reference
enable_rego_lookups: When rego lookups are enabled if the registration plate is provided, but no VIN is provided for a customer, we will perform a VIN lookup (at additional cost to you) and save the VIN along with the customer. When a customer record includes a VIN number, we can cross-reference the VIN with new vehicle listings posted in the future, and use this to verify that the car being sold is definitely the same car that you are tracking.
customers

If you try to upload an empty list, you will receive a You must upload at least one customer record error.

Example

To perform an example request:

An example response payload is:

You can explore this request further in the .

Check upload status

Once you've queued a customer upload, you may want to check on the upload progress. Sending a GET request to /v2/recapture/upload/{UPLOAD_ID}?region=nz will return information about the upload, including the progress and the number of errors.

The key properties to check the upload progress are total_uploaded_customers and total_processed_customers. Creating a new Recapture customer consists of two steps - uploading and processing - and these two counters reflect the progress made for each of these steps.

Once total_processed_customers is equal to total_uploaded_customers, the upload is complete. If there are any unexpected errors during the upload, total_errors will increase to signify this, but total_processed_customers is inclusive of errors.

Example

To perform an example request:

An example response payload is:

Cancel an upload

If you queue a customer upload and later change your mind, you can cancel the upload, stopping the creation of any more customer records.

The response payload will include the details of the deleted upload.

Example

To perform an example request:

An example response payload is:

Viewing and updating customers

Once you have uploaded a customer list, you are able to use the Customer Recapture API to view your newly uploaded customers, as well as edit and delete individual customer records.

Get a list of all customers

You can use the /v2/recapture/customers?region={REGION} endpoint to retrieve a list of all your Recapture customers.

This list is paginated, and you can move between pages using the offset and limit query parameters.

If you want to get customer records associated with a specific upload, you can pass the unique Upload ID to the upload_id query parameter.

Example

To perform an example request:

An example response payload is:

Get an individual customer's records

You can get individual customer details using the GET method on /v2/recapture/customers/${CUSTOMER_ID}?region=nz.

Trying to look up an invalid customer ID returns the Invalid Customer ID error, and trying to look up a customer that you don't have access to returns an You don't have permission to access that customer error. If you try to look for a customer that exists in a different region than the one specified in the request, you will receive an Incorrect Region error.

Example

To perform an example request:

An example response payload is:

Update an individual customer record

If you need to make changes to an individual customer's details, you can use the PATCH method on the /v2/recapture/customers/${CUSTOMER_ID}?region=nz endpoint.

Only the fields that you specify in the request body will be affected, and providing an empty value ("") will set the field to null where applicable.

The response payload will include the updated customer object.

You can update any of the following customer properties: - client_name - mobile_number - sale_date - expiry_date

Example

To perform an example request:

An example response payload is:

Delete a customer

You can delete an individual customer by using the DELETE method on the /v2/recapture/customers/{CUSTOMER_ID}?region=nz endpoint.

The response payload includes the details of the customer that was deleted, and there is no way to retrieve the customer other than manually re-creating it.

The same error messages apply as with the Get Customer endpoint.

Example

To perform an example request:

An example response payload is:

{ region: { type: 'string', required: true, description: 'The stock item region', }, created_at: { type: 'string', required: true, description: 'ISO 8601 created at utc date and time string', }, updated_at: { type: 'string', required: true, description: 'ISO 8601 updated at utc date and time string', }, checked_at: { type: 'string', required: true, description: 'ISO 8601 checked at utc date and time string', }, stocked_at: { type: 'string', required: true, description: 'ISO 8601 stocked at utc date and time string', }, removed_at: { type: 'string', required: false, description: 'ISO 8601 removed at utc date and time string, only to be supplied for items that have been removed', }, condition: { type: 'string', required: true, description: 'The stock condition', example: 'New', }, stock_no: { type: 'string', required: false, description: 'The stock number', }, rego: { type: 'string', required: false, description: 'The registration plate', }, rego_expiry: { type: 'string', required: false, description: 'ISO 8601 rego_expiry utc date and time string', }, vin: { type: 'string', required: false, description: 'The Vehicle Identification Number', }, year: { type: 'number', required: false, description: 'The vehicle year', }, kms: { type: 'number', required: false, description: 'The vehicle odometer reading', }, color: { type: 'string', required: false, description: 'The vehicle body colour', }, description: { type: 'string', required: false, description: 'The vehicle description', }, make: { type: 'string', required: false, description: 'The vehicle make', }, model: { type: 'string', required: false, description: 'The vehicle model', }, series: { type: 'string', required: false, description: 'The vehicle series', }, badge: { type: 'string', required: false, description: 'The vehicle badge', }, tranmission: { type: 'string', required: false, description: 'The vehicle tranmission', }, location: { type: 'string', required: false, description: 'The vehicle location', }, suburb: { type: 'string', required: false, description: 'The vehicle suburb', }, postcode: { type: 'string', required: false, description: 'The vehicle postcode', }, lat: { type: 'number', required: false, description: 'The vehicle latitude', }, lng: { type: 'number', required: false, description: 'The vehicle longtitude', }, price_egc: { type: 'number', required: false, description: 'The vehicle price excluding government charges', }, price_dap: { type: 'number', required: false, description: 'The vehicle drive away price', }, purchase_price: { type: 'number', required: false, description: 'The vehicle purchase price', }, video_url: { type: 'string', required: false, description: 'The vehicle video url', }, images: { type: 'array', items: { type: 'object', properties: { url: { type: 'string', required: true, }, }, }, }, }

{ "success": true, "stockItemResult": { "id": "3842b20f-423b-4eab-b87a-69bed4582725", "region": "nz", "lead_id": "3f026858-5b0e-4221-8338-af40fb5d3865", "listing_id": null, "external_id": "000000001", "stock_feed_account_id": "1798a10c-977a-4ba8-b15b-0d9cb581b36b", "source": "ff7ff637-e4c1-40f2-9f9d-8f76d6c201fb", "listing_source": null, "listing_source_id": null, "external_vehicle_catalogue": null, "created_at": "2023-09-28T17:53:33.000Z", "updated_at": "2023-09-28T17:53:33.000Z", "checked_at": "2023-09-28T17:53:33.000Z", "stocked_at": "2023-09-28T17:53:33.000Z", "removed_at": null, "condition": "Used", "stock_no": "8567", "rego": "1REGOYG", "vin": "6FPAAAAAAAAAAAA5", "rego_expiry": "2023-09-28T00:00:00.000Z", "vehicle_id": "agv-ford-3399971153459088", "year": 2023, "compliance_year": null, "compliance_month": null, "build_year": null, "build_month": null, "make": "Ford", "model": "Transit", "badge": "350L", "series": "VO", "vehicle_title": null, "vehicle_rrp": null, "vehicle_age_years": null, "model_year": "MY23", "release_year": 2022, "release_month": 9, "body_type": "Van", "engine_type": "Piston", "transmission_type": "Automatic", "drive_type": "Front Wheel Drive", "fuel_type": "Diesel", "wheelbase_type": null, "body_config_type": null, "range": null, "power_kw": 125, "torque_nm": 390, "num_doors": 4, "num_seats": 3, "num_gears": 6, "num_cylinders": 4, "capacity_cc": 1995, "matcher_input": "year 2023 make FORD model TERRITORY series SZ badge transmission 6 SP AUTOMATIC ", "matcher_inputs": { "make": "FORD", "year": 2023, "badge": "", "model": "TERRITORY", "series": "SZ", "transmission": "6 SP AUTOMATIC" }, "kms": 150000, "color": null, "description": null, "purchase_price": null, "costs": null, "acquisition_channel": null, "purchaser": null, "est_retail": 35266, "est_trade": 29976, "price_egc": 36999, "price_dap": 55000, "price_includes_govt_charges": null, "price_egc_rel_to_est_trade": 1.234287429943955, "price_egc_diff_to_est_trade": 0.2342874299439552, "price_egc_rel_to_est_retail": 1.049140815516361, "price_egc_diff_to_est_retail": 0.04914081551636129, "video_url": null, "is_certified": null, "location_input": "", "state": null, "suburb": "Bluewood", "suburb_input": "Bluewood", "postcode": "3200", "postcode_input": "3200", "lat": 55.4324, "lng": -42.432, "formatted_location": null, "raw_payload": { "kms": 150000, "lat": 55.4324, "lng": -42.432, "vin": "6FPAAAAAAAAAAAA5", "make": "FORD", "rego": "1REGOYG", "year": 2023, "badge": "", "model": "TERRITORY", "images": [], "region": "nz", "series": "SZ", "suburb": "Bluewood", "location": "", "postcode": "3200", "stock_no": "8567", "condition": "Used", "price_dap": 55000, "price_egc": 36999, "checked_at": "2023-09-28T17:53:33Z", "created_at": "2023-09-28T17:53:33Z", "stocked_at": "2023-09-28T17:53:33Z", "updated_at": "2023-09-28T17:53:33Z", "rego_expiry": "2023-09-28T17:53:33Z", "transmission": "6 SP AUTOMATIC" }, "pipeline_state_id": 19 } }

Webhooks Integration

Receive notifications from AutoGrab system on events to power your own experiences.

The Webhooks API allows you to configure endpoints that will receive PUSH events from AutoGrab.

This API requires authentication and an appropriate license attached to it.

Webhook Events

There are several types of events that you can listen to using the Webhooks API. The names and descriptions of each of these events are included below.

You can find example payloads for each of these events at the bottom of this page.

Name

Definition

Currently, only the ping, recapture_new and price_change events are in use. You can still configure your webhooks to listen to the other events to enable these events once they are supported.

If you need immediate access to Recapture price change and delist events for your use case, please reach out to us at [email protected]

Create a new Webhook

To set up a webhook event subscriber, you'll first need to create the webhook using the webhook API.

You must provide a few options in the request body:

name: A name for the webhook. This is used for reference only.
region: The region that you want to subscribe to events in (nz)
format: The format that you want the PUSH events to be sent in (Currently, only

Example

To perform an example request:

An example response payload is:

You can explore this request further in the .

Get a list of your webhooks

A GET request to /v2/webhooks?region=nz will return a list of all your configured webhooks in the given region.

Example

To perform an example request:

An example response payload is:

You can explore this request further in the .

Get the configuration of a single webhook

A GET request to /v2/webhooks/{WEBHOOK_ID}?region={REGION} will return the configuration of the webhook with the corresponding ID.

The payloads are the same as the /v2/webhooks route but only a single webhook is returned instead of an array.

If you try to access a webhook in a different region to the one specified in the request, you will receive an Invalid Region error. Additionally, accessing a webhook that your account does not have permission to view will return an You don't have permission to access that webhook error.

If you attempt to view a webhook that doesn't exist, you will receive an Invalid Webhook ID error.

Example

To perform an example request:

An example response payload is:

You can explore this request further in the .

Modify the configuration of a single webhook

A PATCH request to /v2/webhooks/{WEBHOOK_ID}?region={REGION} allows you to modify any of the properties of the corresponding Webhook.

Only the fields specified in the request body will be modified, and passing a blank ("") value will remove the property from the webhook where applicable.

The response includes the updated webhook, as well as a map of every property that changed.

The same errors as the above (GET /v2/webhooks/${WEBHOOK_ID}) request apply, and a Request validation failed error may also be thrown if you provide any invalid Webhook Event names. Refer to the top of this page for a list of Webhook Events and their descriptions.

Example

To perform an example request:

An example response payload is:

You can explore this request further in the .

Delete a webhook

A DELETE request to /v2/webhooks/{WEBHOOK_ID}?region={REGION} will permenantly delete the webhook.

The response payload includes the configuration of the deleted webhook, as seen in the examples below.

You may receive a small number of additional messages on your webhook's endpoint after deleting the webhook due to queued messages being sent through, but no new messages will be sent to your webhook after it has been deleted, and there is no way to recover the webhook without re-creating it.

Example

To perform an example request:

An example response payload is:

You can explore this request further in the .

Ping a webhook

A POST request to /v2/webhooks/{WEBHOOK_ID}/ping?region={REGION} will send a ping event to your webhook with an example payload.

You can't explicitly subscribe to ping events, as it is a special event type that is only sent when requested using this endpoint.

Example

To perform an example request:

An example response payload is:

You can explore this request further in the .

Webhook Payloads

Example payloads for the webhook events that are currently in use are included below.

`ping`

`recapture_new`

`valuation_change`

{ // The Webhook Event type (required) "event": "recapture_new", // The Webhook Event payload (required) "data": { // The Recapture record which has been seen online "customer": { // The internal ID of the Recapture client (required) "id": "05df2f33-1d03-404c-b0c2-dfbecaa65fff", // Required // The ISO timestamp when the event took place (required) "last_updated": "2022-09-03T00:37:57.095Z", // The registration plate that you were tracking (nullable) "rego": "BMT038", // The VIN uploaded for the Recapture customer (nullable) "vin": null, // The name uploaded for the Recapture Customer (nullable) "client_name": "Raph", // The mobile number uploaded for the Recapture Customer (nullable) "mobile_number": "+61 123 456 789", // The ISO formatted sale date uploaded alongside the customer record, if applicable (nullable) "sale_date": "2022-03-02T00:00:00.000Z", // The ISO formatted expiry date for the Recapture customer record, if applicable (nullable) "expiry_date": "2022-11-20T00:00:00.000Z", // The vehicle title, determined by a registration or listing lookup (nullable) "vehicle_title": "2019 Volkswagen Polo 85TSI Comfortline", // Any additional data that was uploaded alongside the customer record (required) "additional_fields": { "notes": "Three free services included in the package" }, // An array including details for each time one of the customer's vehicles was spotted online (required) "sightings": [ { // The date when the vehicle was spotted online (required) "at": "2022-09-03T00:37:57.095Z", // The Lead ID that includes the listing where the vehicle was spotted online (required) "lead_id": "nz_volkswagen_bmt038", // The URL where the vehicle was listed online (required) "listing_url": "https://autotrader.co.nz/used-cars-for-sale/volkswagen/polo/806849", // The title of the listing (required) "listing_title": "2019 Volkswagen Polo 85TSI Comfortline AW Auto MY19", // The price that the vehicle was listed for at the time of capture (nullable) "listing_price": 26890, } ] } } }

{ // The Webhook Event type (required) "event": "valuation_change", // The webhook event payload (required) "data": { // The pricing record which has changed in value "pricing_record": { // The unique Pricing Record ID (required) "id": "a9fb47f6-3d1d-4945-9f4d-f45b12a63797", // The AutoGrab Vehicle ID associated with the pricing record (required) "vehicle_id": "5478860653068288", // The ISO timestamp when the pricing record was first created (required) "created_at": "2022-08-20T07:20:32.412Z", // The registration plate associated with the pricing record (nullable) "rego": "ZXX678", // The registration state associated with the pricing record, if applicable (nullable) "state": "VIC", // The VIN associated with the pricing record (nullable) "vin": null, // The odometer input for the pricing record (required) "kms": 32000, // The current price prediction for the given vehicle at the kilometers entered (required) "price": 36782, // The current predicted retail price (required) "retail_price": 36782, // The current predicted trade price (required) "trade_price": 32100, // The adjustments and overrides that are currently applied to the pricing record (nullable) // Matches the adjustment schema from the `/v2/valuations/predict` endpoint "adjustment": null, // An array of all the recorded valuation changes that this pricing record has had (required) "changes": [ { // The unique change ID (required) "id": "ba4b3912-ae25-44c1-8a66-36ca68fac859", // The change type (valuation or configuration) (required) // A valuation change implies that the market has shifted, // whereas a configuration change is simply a result of your // adjustments/overrides configuration changing "type": "valuation", // The ISO timestamp when the change occurred (required) "at": "2022-09-03T01:03:55.382Z", // The new price (required) "new_price": 36782, // The new retail price (required) "new_retail_price": 36782, // The new trade price (required) "new_trade_price": 32100, // The old price (required) "old_price": 38520, // The old retail price (required) "old_retail_price": 38520, // The old trade price (required) "old_trade_price": 34200 }, { // Any previous changes to the pricing record will also be // included here, following the same schema as above "id": "46610b56-f3c7-4744-8adf-021c0aba1cc4", "type": "configuration", "at": "2022-09-01T03:12:32.524Z", "new_price": 38520, "new_retail_price": 38520, "new_trade_price": 34200, "old_price": 38520, "old_retail_price": 37520, "old_trade_price": 33900 } ] }, // This is a copy of the specific valuation change that caused the webhook to trigger (required) // in case many changes occur in a short time span, this is the source of truth for the // exact change that triggered the event. "change": { "id": "ba4b3912-ae25-44c1-8a66-36ca68fac859", "type": "valuation", "at": "2022-09-03T01:03:55.382Z", "new_price": 36782, "new_retail_price": 36782, "new_trade_price": 32100, "old_price": 38520, "old_retail_price": 38520, "old_trade_price": 34200 } } }