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.

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

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

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.

Other Authentication Methods

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

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

Vehicle Search

Vehicle Searching Basics

Vehicle discovery is the starting place for almost all functions on the AutoGrab API.

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.

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

Example Payload

Registration Plate Search

Find vehicle information from a registration plate.

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.

That would produce the payload below.

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 ().

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 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 , 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 endpoints.

Options - these are fittable (not fitted) options available on this vehicle. If you require fitted (from factory data) use the 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 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.

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

Example Response

Remember you can enrich your VIN payloads with features, .

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.
Be aware of your listing ID and use that for the marketplace_id parameter.
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.

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.

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

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.

Market Statistics

Get key statistics on any vehicle ID

Overview

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

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

An example response is below.

As this endpoint is part of the market overlay route you can enhance your payload with additional features. Refer to

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.

Valuation

Valuation Basics

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.

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

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

Registration & VIN Valuations

Generate a valuation with a Registration Plate or VIN

Registration Valuation

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

{
    "region": "nz",
}

Example Response

{
    "success": true,
    "prediction": {
        "id": "bc3df5a9-0488-4486-acb9-ca22482f127c",
        "vehicle_id": "5804870883868672",
        "kms": 57306,
        "price": 20622,
        "score": 0.9239,
        "retail_price": 20622,
        "trade_price": 17122,
        "adjustment": null
    }
}

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.

This is done to avoid issues where the VIN lookup component of the valuation fails blocking your workflow. In the recommended scenario if your VIN or Rego lookup fails, you can fall back to or informed by the "upstream_vehicle" parameter.

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.

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 .

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.

Update Configuration

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

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.

{
  "region": "nz",
  "odometer": 10000,
  "listing_price": 30000,
  "vehicle_id": "5257788510961664",
  "vin": "2T1BY32E95C347786",
  "rego": "BMT038",
  "vehicle_description": "2015 Toyota Corolla Ascent Automatic",
  "marketplace": "autotrader.co.nz",
  "marketplace_id": "13495712"
}

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.

{
  "success": true,
  "gauge": {
    "id": "b2824bfd-d4a4-45e4-a81a-bed7b92c5cd9",
    "fill": 0.5,
    "listing_price": 24000,
    "market_range_min": 21000,
    "market_range_max": 26000,
    "confidence": 0.85,
    "sample_size": 10,
    "vehicle_title": "2015 Toyota Corolla Ascent Automatic"
  }
}

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.

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

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.

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

Isolate The Vehicle ID

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

- the most common identifier consumers and agents are familiar with.
- for unregistered or for scenarios where a plate is not known
- 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.

Extrapolate Into Your Workflows

Get Market Data

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

- to get all the images attached to the lead inside AutoGrab.
- to get the primary detailed description of each listing for UI display purposes.

Perform A Valuation

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.

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

Real-Time Pricing

At a minimum, a vehicle ID parameter must be included in the URL, as you can see below: https://app.autograb.com.au/pricing?vehicleId=6673067719786496 You will need to include a rego, vin and/or state parameter to pre-fill the registration search box without running a rego lookup. This will associate the pricing record with the correct rego and VIN and enable easy access to PPSR lookups as those details will also be pre-filled: https://app.autograb.com.au/pricing?vehicleId=6673067719786496&rego=CER226&vin=WBATR92040LE26311&state=VIC Ideally, the odometer reading should also be passed in the URL, otherwise, it will default to 0kms. You can use the odometer input with or without the rego/vin inputs, but the vehicle ID is always required. The expected integration pattern assumes your user has access to app.autograb already. If they are not signed in they will be asked to. You can find the vehicle ID by using a v as you would have already done in your product.

Sourcing

To jump to a specific vehicle in sourcing you can provide identifiers in the following URL patterns. If the identifier is not able to be matched to a vehicle in sourcing we will notify the user of this in app.

Identifier

URL Example

MyListings

To jump to a specific vehicle in MyListings you can provide identifiers in the following URL patterns. If you pass in an identifier that is not associated with the logged in dealer we will show an error popup notifying the user of this.

Identifier

URL Example

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:

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.

Recapture

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

Uploading Customer lists

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

Customer lists are often very long, so the 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={REGION} will initiate a new queued Customer list upload.

The request body has the following parameters:

name: A name to assign to the upload, for personal reference
enable_rego_lookups: When rego lookups are enabled, if the registration plate (and state, if in Australia) 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 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.

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

Example

To perform an example request:

This endpoint returns a 202 Accepted response. An example response payload is:

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={REGION} 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 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 Customers.

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

Example

To perform an example request:

An example response payload is:

Managing Customers

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

Get a list of all Customers

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

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

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

The response includes a total field with the overall count of Customers matching the query, which is useful for paginating through large lists.

Example

To perform an example request:

An example response payload is:

Create an individual Customer

You can create a single Customer directly using the PUT method on the /v2/recapture/customers?region={REGION} endpoint.

The request body has two parameters:

enable_rego_lookups: When enabled, if a registration plate is provided but no VIN, we will perform a VIN lookup (at additional cost). Defaults to false.
customer: An object with the Customer's details. At least a rego or a vin must be provided.

If neither rego nor vin is provided, you will receive a Missing required properties error.

Example

To perform an example request:

An example response payload is:

Get an individual Customer

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

Trying to lookup 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 a You don't have permission to access that customer error.

Example

To perform an example request:

An example response payload is:

Update an individual Customer

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={REGION} endpoint.

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

The response payload will include the updated Customer object.

You can update any of the following Customer properties: external_id, sale_date, monitor_start_date, monitor_end_date, additional_fields

sale_date, monitor_start_date, and monitor_end_date must be valid date strings if provided.

Example

To perform an example request:

An example response payload is:

Delete an individual Customer

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

The response payload includes the details of the Customer that was deleted.

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

Example

To perform an example request:

An example response payload is:

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)

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`

Authorizations

ApiKeystringRequired

Path parameters

vehicle_idstringRequired

Query parameters

minimum_daysnumberOptional

The minimum number of days to show listings for

include_adjacent_yearsbooleanOptional

If enabled, vehicles that were manufactured up to one year before and one year after your chosen vehicle will also be included in the results.

exclude_outliersbooleanOptional

If enabled, leads that are considered outliers will be excluded from the results.

exclude_all_delistedbooleanOptional

If enabled, leads that are not currently on the market will be excluded from the results.

include_all_activebooleanOptional

If enabled, all listings that are currently on the market will be returned, instead of only listings which were uploaded within the specified timeframe (minimum_days). Additionally, if this is enabled, delisted leads will be returned based on the number of days since they were sold, rather than the number of days since they were listed.

include_trashbooleanOptional

If enabled, leads that are considered trash, written off, damaged, or missing details will be included in the results. The tag_ids array can then be used to determine if a lead is trash, damaged, etc.

featuresstringOptional

Comma separated array of additional overlay feature codes as specified in your contract

odometer_range_minnumberOptional

The minimum range observed against similar vehicles

odometer_range_maxnumberOptional

The maximum range observed against similar vehicles

regionstring · enumOptional

The region to perform this request in

Possible values:

reference_idstringOptional

An optional reference id which will be stored against usage records if supplied

Responses

200

Success

application/json

successbooleanOptional

sample_sizenumberOptional

The number of leads in the given market overlay

days_checkednumberOptional

The number of days checked when going back to retrieve relevant leads

avg_days_to_sellnumberOptional

The average number of days to sell for delisted leads in this overlay. If there are no delisted leads in time timespan selected, this will be null.

outlier_countnumberOptional

The count of outliers detected in similar vehicles.

days_supplynumberOptional

The sale rate of vehicles of the sample time period.

avg_pricenumberOptional

The average price of the analysed similar vehicles.

min_pricenumberOptional

The minimum price of the analysed similar vehicles.

max_pricenumberOptional

The maximum price of the analysed similar vehicles.

avg_odometernumberOptional

The average odometer of the analysed similar vehicles.

min_odometernumberOptional

The minimum odometer of the analysed similar vehicles.

max_odometernumberOptional

The maximum odometer of the analysed similar vehicles.

idstringOptional

The AutoGrab Lead ID

colorstringOptional

The color of the vehicle, if applicable

drive_away_pricenumberOptional

The drive-away price

is_outlierbooleanOptional

Is the lead considered an outlier

kmsnumberOptional

The odometer reading for the listed vehicle

listing_urlstringOptional

The URL where the vehicle was listed for sale

listing_sourcesstring[]Optional

A list of marketplaces where the vehicle was listed for sale

listed_atstringOptional

The timestamp when the lead was posted online

pricebooleanOptional

The latest listing price

price_before_govt_chargesnumber[]Optional

The price before government charges

price_includes_govt_chargesboolean[]Optional

Indicates whether the price includes government charges

release_yearnumberOptional

The year when the vehicle or the vehicle's body design was released

release_monthnumberOptional

The calendar month as a number (1-12) when the vehicle or the vehicle's body design was released

removed_atstringOptional

The timestamp when the lead was sold or the listing was removed, or null when the listing is still active

seller_typestring · enumOptional

The type of seller that posted the listing

Possible values:

statestringOptional

The state or province where the vehicle was listed for sale in, or null when no location is specified

tag_idsstring[]Optional

An array of the tags applied to the lead on AutoGrab

vehicle_idstringOptional

The AutoGrab Vehicle ID

yearnumberOptional

The manufacturer year of the vehicle

all_imagesstring[]Optional

All images in the overlay lead

primary_descriptionstringOptional

The primary description of the overlay lead

400

Bad Request

application/json

errorbooleanOptionalDefault: true

messagestringOptional

Error message

401

Unauthorized

application/json

errorbooleanOptionalDefault: true

messagestringOptional

Error message