1 of 51

🇳🇿 NZ AutoGrab API Doc

AutoGrab Basics

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

Production V2

https://api.autograb.com.au/v2/

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

Country

Region Code

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.

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.

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

Outcome

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

/valuations/predict
/valuations/vins
/valuations/registrations

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

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.

Authorization: ApiKey {your API key}

Other Authentication Methods

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

Vehicle Search

Facet Integration Worked Example

Read a step by step example guide on how to work with Facets.

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

Form your GET request for makes

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

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

Form your request for a list of Models

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

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 to see what's available.

Vehicle Data

Vehicle History

Request a vehicles history on marketplaces

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

Example

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.

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

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

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

        ]
    }
}
```

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

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

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

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

Coverage

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

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

Abarth
Alfa Romeo
Alpina
Audi

Valuation

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 authentication and an appropriate license attached to it.

To use the API, a Vehicle ID returned from the Vehicle Search API or Vehicle Facet API is required.

Example

Request

To retrieve a Vehicle ID, use the .

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

{
    "region": "nz",
    "vehicle_id": "5804870883868672"
    "kms": 30000,
    "condition_score": 2
}

The is optional and can be used to further refine your pricing prediction.

Payload

{
    "success": true,
    "prediction": {
        "id": "a2955915-9611-40ef-8b98-b827dad76ff4",
        "vehicle_id": "5804870883868672",
        "kms": 57306,
        "price": 20622,
        "score": 0.9239,
        "retail_price": 20622,
        "trade_price": 17122,
        "adjustment": null
    }
}

Pricing ID

The payload returned by price prediction requests will include an ID, which you can use to refer to the pricing request in the future. The /v2/valuations/history/{PRICING_ID method will return the response from a previous pricing request, and you can also use the Pricing ID to track price changes with the Price Changes API, if licenced.

To get a paginated list of all your previous price predictions, you can use the /v2/valuations/history endpoint.

By supplying a condition score, you can manipulate the trade_price returned by the prediction endpoint. The condition score can be between 1 and 5. A condition of 1 being poor condition and a condition of 5 excellent condition.

Supplying any other numbers will return the default trade_price which assumes excellent condition.

If you're building a user interface where you allow the user to choose a condition it is recommended you follow the industry standard in the table below.

Condition

Condition Score

Registration & VIN Valuations

Generate a valuation with a Registration Plate or VIN

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

Example Response

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

Example Response

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.

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.

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.

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.

You must implement your own trigger button to launch the iframe and load in all required inputs as below.

Example Implementation Inputs

To load the iframe you need to share the following input variables.

Label

Description

Example

Requirement

The system will take the most economically logical identifier and fall back to others when provided with options. The preference list is below.

If provided with a Vehicle_Description it will use that.
If not, VIN will be used,
If not, Registration

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_INSIGHTS_HIDE to event listening to close the popup container and AUTOGRAB_INSIGHTS_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_INSIGHTS_DIMENSIONS alert.

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

AUTOGRAB_INSIGHTS_SUCCESS

The widget loaded successfully, no intervention is needed.

AUTOGRAB_INSIGHTS_ERROR

An exception or error was delivering the iframe contents.

AUTOGRAB_INSIGHTS_HIDE

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

AUTOGRAB_INSIGHTS_DIMENSIONS

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

Other Products & Resources

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. https://app.autograb.com.au/pricing?vehicleId=6673067719786496&rego=CER226&vin=WBATR92040LE26311&state=VIC&kms=10000 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 vehicle search mechanism as you would have already done in your product.

This URL strategy will not submit the valuation request, your user will need to push the button.

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

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

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.
monitor_start_date: An optional default date from which Customers in this upload should start being monitored. Applied to any Customer that does not specify its own monitor_start_date.
monitor_end_date: An optional default date after which Customers in this upload should stop being monitored. Applied to any Customer that does not specify its own monitor_end_date.
customers: An array of the Customers that you want to upload. Customers can have any of the following properties, but everything is optional (however, at least a rego OR a vin is necessary for tracking purposes):
- rego: The registration plate of the Customer's vehicle
- vin

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:

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:

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
Do not use “AutoGrab” in the name of your application or integration
Clearly state that the integration is built by you — and not AutoGrab
Do not use a name that is confusingly similar to AutoGrab or infringes on any other trademarks

The logo and wordmark are the most prominent elements of the AutoGrabs brand and it’s important to use them correctly.

Detailed instructions for the usage of our brand assets are provided via our dedicated brand usage guide.

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.

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.
monitor_start_date: An optional default date from which Customers in this upload should start being monitored. Applied to any Customer that does not specify its own monitor_start_date.
monitor_end_date: An optional default date after which Customers in this upload should stop being monitored. Applied to any Customer that does not specify its own monitor_end_date.
customers: An array of the Customers that you want to upload. Customers can have any of the following properties, but everything is optional (however, at least a rego OR a vin is necessary for tracking purposes):
- rego: The registration plate of the Customer's vehicle
- vin

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

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:

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

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:

get

Get the leads used to justify pricing for a given AutoGrab Vehicle ID.

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

get/v2/sourcing/market_overlay/{vehicle_id}

GET /v2/sourcing/market_overlay/{vehicle_id} HTTP/1.1
Host: api.autograb.com.au
ApiKey: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "sample_size": 1,
  "days_checked": 1,
  "avg_days_to_sell": 1,
  "outlier_count": 1,
  "days_supply": 1,
  "avg_price": 1,
  "min_price": 1,
  "max_price": 1,
  "avg_odometer": 1,
  "min_odometer": 1,
  "max_odometer": 1,
  "leads": [
    {
      "id": "text",
      "color": "text",
      "drive_away_price": 1,
      "is_outlier": true,
      "kms": 1,
      "listing_url": "text",
      "listing_sources": [
        "text"
      ],
      "listed_at": "text",
      "price": true,
      "price_before_govt_charges": [
        1
      ],
      "price_includes_govt_charges": [
        true
      ],
      "release_year": 1,
      "release_month": 1,
      "removed_at": "text",
      "seller_type": "private",
      "state": "text",
      "tag_ids": [
        "text"
      ],
      "vehicle_id": "text",
      "year": 1,
      "all_images": [
        "text"
      ],
      "primary_description": "text"
    }
  ]
}

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 info@autograb.com.au

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)

To perform an example request:

An example response payload is:

You can explore this request further in the .

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

To perform an example request:

An example response payload is:

You can explore this request further in the .

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 .

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 .

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 .

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 .

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

🇳🇿 NZ AutoGrab API Doc

AutoGrab Basics

Integration Overview

Overview

Environments

Regions

API Test Cases

Test Cases

Authentication

Basic Key Based Authentication

Key Types

Secret API Key

Public API Key

Authenticating Requests

Other Authentication Methods

Vehicle Search

Facet Integration Worked Example

Sourcing

Sourcing Basics

Market Statistics

Vehicle Data

Vehicle History

Factory Build Data

Overview

Coverage

Valuation

Valuation Predictions

Overview

Example

Pricing ID

Registration & VIN Valuations

Embeddable Products

Embeddable Basics

Market Insights Snapshot

Overview

Implementation

Example Implementation Inputs

Other Products & Resources

URL Linking Structure

Real-Time Pricing

Sourcing

Recapture

Uploading Customer lists

Brand Guidelines

Naming Apps and Integrations

Basic Key Based Authentication

Key Types

Secret API Key

Public API Key

Authenticating Requests

Other Authentication Methods

API Test Cases

Test Cases

Market Statistics

Supported Endpoints

Implementation Guide

Overview

Embeddable Basics

Deal Gauge & Indicator

Valuation Widget

Market Insights Snapshot

Factory Build Data

Overview

Coverage

Facet Integration Worked Example

Vehicle History

Registration & VIN Valuations

Registration Valuation

VIN Valuation

Implementation Constrains

Overview

Example

Vehicle History Events

Example

Features

Market Insights Snapshot

Overview

Implementation

Example Implementation Inputs

Vehicle Identifier Preferences