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

OAuth integration consists of 2 basic components:

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

2. REST API call signing using a valid token

Token management

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

auth-broker POST call to receive a valid OAuth token

Copy

POST !!!!!!!!/request-token

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

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

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

REST api call signing

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

Troubleshooting

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

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

Test Cases

The test cases relate to each other with all related to the same set of vehicle IDs dependant on region.

Supported Endpoints

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

• /valuations/predict

• /valuations/vins

• /valuations/registrations

• /valuations/residual

• /valuations/predict/conditions

• /sourcing/market_overlay

• /sourcing/market_overlay/statistics

Implementation Guide

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

Overview

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

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

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.

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

Report Features

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

Vehicle Identification

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

• VIN

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

• Odometer

Valuation

A previous valuation can be included in the report generation by adding the following data. What data is used for the valuation is determined on priority:

Price Record ID

If the pricing record ID is passed in the request, the associated valuation will populate the report. A valuation ID is generated using the endpoint and contained in the response. So, a valuation call needs to be performed before generating the report.

Lead ID

A lead ID is obtained from the endpoint and is the tier 2 valuation source.

Odometer

If no Pricing or Lead ID is provided but an odometer is, the odometer will be used to perform a valuation with the same logic as the endpoint.

Brand

Controls White labeling of the report

Marketplace Specific Fields

When using reports integrated within a marketplace additional fields can be included in the request to allow for data from the marketplace listing to be displayed in the report.

• Marketplace Image URL

  • URL to a public image from the marketplace listing, will replace the stock photo contained in a standard CarAnalysis Report

• Marketplace Price

  • The price displayed on the listing on the marketplace.

  • Note it is not possible to use the marketplace price and the valuation source in the same report.

• Marketplace Price Type

  • Displays the type of price for the Marketplace price being provided.

Sources

The sources enum determines additional features that are included within the report PDF, the report is modular. However, it is recommended to include Vehicle Details at a minimum

Vehicle Details

Populates the Vehicle Information at the top of the report. It is recommended that vehicle details always be included as it contains the minimum identifiable information into the report.

Odometer History

It will display a table of all recorded odometer listings that AutoGrab has. Based on the odometer from previous listings, it can highlight the possibility of odometer rollback events.

Build Data

It will populate a table with built-data information, which is the same data obtainable from the endpoint in PDF format.

Fitted Options

Not currently available

Valuation

Whether to include an AutoGrab valuation in the report

Report White Labeling

AutoGrab can create custom-branded templates for the Car Analysis report. Please reach out to your AutoGrab representative for more information on building a custom template.

Obtaining Generated Reports

Due to the Car Analysis report reaching out to external endpoints and co-lating data the report is not generated immediately. It is recommended that the ID for the report be stored for future use or that the PDF be obtained again later.

To obtain the requested report, pass the ID from the POST to the get endpoint.

Example Report

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 operates on a tiered system of queries:

VIN - The first initial call can be made to VIN + Region. However, if VIN does not return any history information, the following data is required as a fallback.

• Year

• Make

• Model

• Registration

Vehicle History Events

The Vehicle History endpoint delivers detailed information on events related to a listing. The following events are possible on a given listings.

Listing - the detection of a listing being added to its relevant marketplace.

  {
      "type": "listing",
      "odometer": 100000,
      "price": 100000,
      "marketplace": "Gumtree",
      "timestamp": "2022-09-20T10:22:07.072",
      "seller_type": "string"
    }

Delisting - the detection of a listing being removed from its relevant marketplace, this is frequently and reliably related to a sale of the vehicle.

  {
      "type": "delisting",
      "odometer": 100000,
      "price": 100000,
      "marketplace": "Gumtree",
      "timestamp": "2022-09-20T10:22:07.072",
      "seller_type": "string"
    }

Price Change - the detection of a movement in the price, see the features section below for more information.

Example

To perform an example request:

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

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

{
  "success": true,
  "id": "dfe4d117-74e1-4545-9e79-a0baac8208a7",
  "events": [
    {
      "type": "listing",
      "odometer": 100000,
      "price": 100000,
      "marketplace": "Gumtree",
      "timestamp": "2022-09-20T10:22:07.072",
      "seller_type": "string"
    }
  ]
}

Features

You can opt to enrich your vehicle history payload by passing in a feature or features separated by commas.

curl '/v2/sourcing/history?region=au&registration_plate=BMT038&state=VIC&year=2019&make=Volkswagen&features=price_changes&model=Polo&vin=KL3TA48E9CB053071'
      -H 'ApiKey: {API_KEY}'

Price Changes

Currently we support the price_changes feature that will show you fluctuations in the price. Passing this feature will return upward on downward movements in the listings price.

Contact your sales rep to understand your commercial rate card for each feature.

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.

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

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

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

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

Coverage

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

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

• Abarth

• Alfa Romeo

• Alpina

• Audi

• Bentley

• BMW

• Buick

• Cadillac

• Chevrolet

• Chrysler

• Citroën

• Dacia

• Daewoo

• Dodge

• DS

• Fiat

• Ford

• GMC

• Hummer

• Hyundai

• Isuzu

• Jaguar

• Jeep

• KIA

• Lancia

• Land Rover

• Lincoln

• Maybach

• Mercedes-Benz

• MINI

• Opel

• Porsche

• Peugeot

• Renault

• Rolls-Royce

• Saab

• SEAT

• Skoda

• smart

• Vauxhall

• Volkswagen

• Volvo

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

Query Parameters

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

Base parameters

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

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

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

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

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

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

<iframe
src="http://localhost:3000?region=uk&odometer=10000&listing_price=100
00&vin=MM0DK2W7A0W207162&api_key={yourkey}"
/>

With Rego & State

<iframe
src="http://localhost:3000?region=uk&odometer=10000&listing_price=100
00&rego=AOM964&state=VIC&api_key={yourkey}"
/>

With Marketplace/Marketplace ID

<iframe
src="http://localhost:3000/?region=uk&odometer=10000&listing_price=10
000&marketplace=carsales.com.au&marketplace_id=OAG-AD-21662144&api_ke
y={yourkey}"
/>

With Vehicle Description

<iframe
src="http://localhost:3000/?region=uk&odometer=10000&listing_price=10
000&vehicle_description=2017%20Mazda%20CX-3%20Maxx&api_key={yourkey}"
/>

Local Testing

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

<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width,
initial-scale=1.0" />
<title>Iframe Test</title>
</head>
<body>
<iframe
src="https://gauge.autograb.com.au?region=uk&odometer=10000&listing_p
rice=26005&vin=MM0DK2W7A0W207162&api_key={yourkey}"
width="100%"
height="600px"
></iframe>
</body>
</html>

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:

window.addEventListener('message', event => {
if (
event.data === 'AUTOGRAB_GAUGE_SHOW' &&
event.origin === 'https://gauge.autograb.com.au'
) {
// show the gauge iframe element
}
});
If there is a redirect to the 500 page, we send a message via the iframes postMessage
function.. The 500 page is used for any error that occurs server side, as well as if the gauge
valuation is below the threshold defined in your configuration (this is per API key).
The way for a client to listen for the event is as follows:
window.addEventListener('message', event => {
if (
event.data === 'AUTOGRAB_GAUGE_HIDE' &&
event.origin === 'https://gauge.autograb.com.au'
) {
// hide the gauge iframe element
}
});

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

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 the Facets API is Westside Auto.

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

Facet Integration Worked Example

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=au&facet=make

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

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

Form your request for a list of Models.

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

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

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

Form your request for a list of Badges

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

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

Select A Badge A Load Vehicles From A Search

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

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

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

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

If you do not pay attention to the counts under each facet, there may be too many vehicles to search for. You will know you have triggered this limitation if you see the error below

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

Overview

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

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.

Creating a stock feed

Your organisation will need at least one stock feed before uploading stock to the platform.

Overview

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

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.

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.

Overview

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

Prerequisites to access.

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

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

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

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.

Overview

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

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

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

Example Implementations

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

Implementation

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

Position On Page

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

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

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

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.

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

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

Example Response

{
    "vehicle": {
        "id": "5655899674771456",
        "region": "uk",
        "title": "2017 Toyota Hilux SR5 Auto 4x4 Double Cab",
        "year": "2017",
        "make": "Toyota",
        "model": "Hilux",
        "badge": "SR5",
        "series": "GUN126R",
        "model_year": "MY17",
        "release_month": 7,
        "release_year": 2015,
        "body_type": "Utility",
        "body_config": "Dual Cab",
        "transmission": "Sports Automatic",
        "transmission_type": "Automatic",
        "wheelbase": null,
        "wheelbase_type": null,
        "fuel": "Diesel",
        "fuel_type": "Diesel",
        "engine": "Piston",
        "engine_type": "Piston",
        "drive": "4x4 Dual Range",
        "drive_type": "Four Wheel Drive",
        "num_doors": 4,
        "num_seats": 5,
        "num_gears": 6,
        "num_cylinders": 4,
        "capacity_cc": 2755,
        "power_kw": 130,
        "torque_nm": 450,
        "range": 1127,
        "options": [
        ]
    },
    "success": true
}

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

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

This API requires 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=uk 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: 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: The Vehicle Identification Number corresponding to the customer's vehicle

• client_name: The name of the customer/client, for reference purposes

• mobile_number: The customer's phone number. This is used for reference purposes, as well as to find other listings that the same customer has posted online.

• sale_date: The date that the vehicle was sold to the customer, if applicable. For reference only.

• expiry_date: If provided, the customer will be automatically deleted from our system on this date. This may be useful for insurance clients where the customer is no longer of interest after a policy ends, for instance.

• additional_fields: A map of any other properties that should be saved along with the customer record.

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=uk 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=uk 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=uk.

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 an You don't have permission to access that customer error. If you try to lookup 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=uk 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=uk 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:

Overview

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

Environments

Regions

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

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

Supported Regions

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.

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

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

Workflow Overview

Isolate The Vehicle ID

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

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

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

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

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

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

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

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

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

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.

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 AutoGrab IDs from vehicle search steps you've previously taken. In this case supply your known vehicle_id as part of the request. This is the lowest-cost implementation as it does not require a VIN or Registration search.

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.