1 of 44

🇲🇾 MY AutoGrab API Doc

AutoGrab Basics

AutoGrab Developer Hub

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

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

Integration Overview

Key things to know before you start.

Overview

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

Environments

Environment

URL

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=au be included where region is required.

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

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

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.

FAQ

These are frequently asked questions about AutoGrab and our products.

Authentication

API Key

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 OAuth, you can read more about this authentication mechanism here.

OAuth Authentication

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:

Token management (ensure your system always has a valid OAuth token available)
REST api call signing using a valid token

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

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 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), the number plate, and the API key. It will return either a matching vehicle or a null.

If a matching vehicle cannot be identified in all cases, we will return the upstream_vehicle field, allowing you to identify how the relevant road transport authority describes the car. Depending on your use case, you may wish to allow front-end users to manually classify the vehicle using the guide to fill out a Facet-style search.

Features

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

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

Extended Data

This feature will return an extended payload of vehicle data from the registration authority. Use features=extended_data to receive this payload.

   "extended_data": {
        "body_type_description": "CAR/SEDAN",
        "color_description": "WHITE",
        "engine_number": "DKJ039523",
        "make_code": "VOLKS",
        "make_description": "",
        "model_code": "",
        "model_description": "POLO",
        "vehicle_type_description": "CAR / SMALL PASSENGER VEHICLE"

Upstream Data

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

This feature will return the options fitted to the vehicle based on your . It will show all options, the price and if it is fitted to the vehicle or not. Usefeatures=build_data

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.

Marketplace ID Lookup

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

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.

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.

Stock Feeds

Pipe your stock feed into a range of AutoGrab products.

Creating a stock feed

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

To create a stock feed, make a single POST request to the following Autograb API:

POST /v2/stock?region=au

Sample response:

{
    "success": true,
    "stockFeed": {
        "id": "ff7ff637-e4c1-40f2-9f9d-8f76d6c201fb",
        "display_name": "ff7ff637-e4c1-40f2-9f9d-8f76d6c201fb",
        "stock_feed_api_keys": [
            "YOUR_API_KEY"
        ]
    }
}

The stock feed ID is required to post stock items to AutoGrab. Please note the stock feed is linked to your API key, so you will need to use the same API key when posting stock items to the stock feed.

Stock item schema

Stock items must be posted in a format that complies with the Autograb Stock item schema:

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

Posting stock items

To post a stock item, make a single POST request to the following AutoGrab API:

POST /v2/stock/{stock_feed_id}/{external_dealership_id}/{external_id}?region=au

Post payload should be the stock item payload, as detailed above. Note that you need to provide your stock_feed_id, as well as external_dealership_id (that is, your own dealership identifier external to AutoGrab) and the stock item external_id (that is, your own stock item identifier, external to AutoGrab).

When you post stock to AutoGrab, the system will overwrite any previous stock with the latest details contained in the post payload.

Sample response:

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.

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.

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

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.

/v2/valuations/max_offer_configuration

Gauge API

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.

Using /v2/valuations/gauge/ you can generate responses to make your own AutoGauges. The post body you use depends on the data you have and the commercial model you are open to.

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": "au",
  "odometer": 10000,
  "listing_price": 30000,
  "vehicle_id": "5257788510961664",
  "vin": "2T1BY32E95C347786",
  "rego": "BMT038",
  "state": "VIC",
  "vehicle_description": "2015 Toyota Corolla Ascent Automatic",
  "marketplace": "autotrader.com.au",
  "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.

{
  "region": "au",
  "odometer": 10000,
  "listing_price": 30000,
  "marketplace": "example.com.au",
  "marketplace_id": "53445712"
}

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.

{
  "region": "au",
  "odometer": 10000,
  "listing_price": 30000,
  "vehicle_id": "5257788510961664",
  "vehicle_description": "2015 Toyota Corolla Ascent Automatic",
}

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.

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.

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

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

REPORTS

Car Analysis

Generate PDF reports of vehicles for users

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

The CarAnalysis report contains a stock photo and vehicle-specific information. This is generated using the VIN or Registration and State. Provide all three wherever possible to obtain the most accurate information possible for report generation.

Valuation

A 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 Valuation 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 Sourcing 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 Valuation endpoint.

Sources

What sources are available with your account are controlled at a feature level. To access particular sources, don't hesitate to get in touch with your AutoGrab representative.

The sources enum determines additional features that are included within the report PDF.

A PPSR report provided by the government will be attached to the end of the PDF

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.

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.

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

Not currently implemented

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.

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.

Recapture

Insurance

Pre-Accident Valuation

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 AutoGrab ID to progress through the wider set of AutoGrab data. You can do this in four common ways;

Registration Plate Search - 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.

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.

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.

If you need more information than is provided in the registration lookup you can access 200+ fields on every vehicle via the . This could help you describe or highlight differences between vehicles.

{
    "success": true,
    "vehicles": [
        {
            "id": "4678970977026048",
            "legacy_id": "4678970977026048",
            "badge": "GTI",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo GTI AW Auto MY19",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Automatic",
            "wheelbase_type": null,
            "capacity_cc": 1984,
            "power_kw": 147,
            "torque_nm": 320,
            "range": 784,
            "num_cylinders": 4,
            "num_doors": 5,
            "num_gears": 6,
            "num_seats": 5,
            "model_year": "MY19",
            "release_month": 8,
            "release_year": 2018
        },
        {
            "id": "4960445953736704",
            "legacy_id": "4960445953736704",
            "badge": "70TSI Trendline",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo 70TSI Trendline AW Manual MY19",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Manual",
            "wheelbase_type": null,
            "capacity_cc": 999,
            "power_kw": 70,
            "torque_nm": 175,
            "range": 1000,
            "num_cylinders": 3,
            "num_doors": 5,
            "num_gears": 5,
            "num_seats": 5,
            "model_year": "MY19",
            "release_month": 8,
            "release_year": 2018
        },
        {
            "id": "5241920930447360",
            "legacy_id": "5241920930447360",
            "badge": "85TSI Comfortline",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo 85TSI Comfortline AW Manual MY19",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Manual",
            "wheelbase_type": null,
            "capacity_cc": 999,
            "power_kw": 85,
            "torque_nm": 200,
            "range": 909,
            "num_cylinders": 3,
            "num_doors": 5,
            "num_gears": 6,
            "num_seats": 5,
            "model_year": "MY19",
            "release_month": 8,
            "release_year": 2018
        },
        {
            "id": "5804870883868672",
            "legacy_id": "5804870883868672",
            "badge": "85TSI Comfortline",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo 85TSI Comfortline AW Auto MY19",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Automatic",
            "wheelbase_type": null,
            "capacity_cc": 999,
            "power_kw": 85,
            "torque_nm": 200,
            "range": 909,
            "num_cylinders": 3,
            "num_doors": 5,
            "num_gears": 7,
            "num_seats": 5,
            "model_year": "MY19",
            "release_month": 8,
            "release_year": 2018
        },
        {
            "id": "6367820837289984",
            "legacy_id": "6367820837289984",
            "badge": "70TSI Trendline",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo 70TSI Trendline AW Auto MY19",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Automatic",
            "wheelbase_type": null,
            "capacity_cc": 999,
            "power_kw": 70,
            "torque_nm": 175,
            "range": 930,
            "num_cylinders": 3,
            "num_doors": 5,
            "num_gears": 7,
            "num_seats": 5,
            "model_year": "MY19",
            "release_month": 8,
            "release_year": 2018
        },
        {
            "id": "4936256697925632",
            "legacy_id": "4936256697925632",
            "badge": "85TSI Comfortline",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo 85TSI Comfortline AW Auto MY20",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Automatic",
            "wheelbase_type": null,
            "capacity_cc": 999,
            "power_kw": 85,
            "torque_nm": 200,
            "range": 889,
            "num_cylinders": 3,
            "num_doors": 5,
            "num_gears": 7,
            "num_seats": 5,
            "model_year": "MY20",
            "release_month": 7,
            "release_year": 2019
        },
        {
            "id": "5217731674636288",
            "legacy_id": "5217731674636288",
            "badge": "85TSI Style",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo 85TSI Style AW Auto MY20",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Automatic",
            "wheelbase_type": null,
            "capacity_cc": 999,
            "power_kw": 85,
            "torque_nm": 200,
            "range": 889,
            "num_cylinders": 3,
            "num_doors": 5,
            "num_gears": 7,
            "num_seats": 5,
            "model_year": "MY20",
            "release_month": 7,
            "release_year": 2019
        },
        {
            "id": "5499206651346944",
            "legacy_id": "5499206651346944",
            "badge": "70TSI Trendline",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo 70TSI Trendline AW Auto MY20",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Automatic",
            "wheelbase_type": null,
            "capacity_cc": 999,
            "power_kw": 70,
            "torque_nm": 175,
            "range": 909,
            "num_cylinders": 3,
            "num_doors": 5,
            "num_gears": 7,
            "num_seats": 5,
            "model_year": "MY20",
            "release_month": 7,
            "release_year": 2019
        },
        {
            "id": "6062156604768256",
            "legacy_id": "6062156604768256",
            "badge": "85TSI Comfortline",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo 85TSI Comfortline AW Manual MY20",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Manual",
            "wheelbase_type": null,
            "capacity_cc": 999,
            "power_kw": 85,
            "torque_nm": 200,
            "range": 909,
            "num_cylinders": 3,
            "num_doors": 5,
            "num_gears": 6,
            "num_seats": 5,
            "model_year": "MY20",
            "release_month": 7,
            "release_year": 2019
        },
        {
            "id": "6343631581478912",
            "legacy_id": "6343631581478912",
            "badge": "GTI",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo GTI AW Auto MY20",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Automatic",
            "wheelbase_type": null,
            "capacity_cc": 1984,
            "power_kw": 147,
            "torque_nm": 320,
            "range": 784,
            "num_cylinders": 4,
            "num_doors": 5,
            "num_gears": 6,
            "num_seats": 5,
            "model_year": "MY20",
            "release_month": 7,
            "release_year": 2019
        },
        {
            "id": "6625106558189568",
            "legacy_id": "6625106558189568",
            "badge": "70TSI Trendline",
            "make": "Volkswagen",
            "model": "Polo",
            "series": "AW",
            "title": "2019 Volkswagen Polo 70TSI Trendline AW Manual MY20",
            "year": "2019",
            "body_config_type": null,
            "body_type": "Hatchback",
            "drive_type": "Front Wheel Drive",
            "engine_type": "Piston",
            "fuel_type": "Petrol",
            "transmission_type": "Manual",
            "wheelbase_type": null,
            "capacity_cc": 999,
            "power_kw": 70,
            "torque_nm": 175,
            "range": 976,
            "num_cylinders": 3,
            "num_doors": 5,
            "num_gears": 5,
            "num_seats": 5,
            "model_year": "MY20",
            "release_month": 7,
            "release_year": 2019
        }
    ],
    "total": 11,
    "confidence": "standard"
}

get

Get a vehicle by its registration number

Authorizations

ApiKeystringRequired

Path parameters

plate_numberstringRequired

Plate number of the registered vehicle

Query parameters

statestringOptional

State is used in the AU region to narrow down a numberplate

prefer_more_resultsbooleanOptional

If enabled, a larger selection of vehicles may be returned and a manual selection would be required to select the correct vehicle. This is disabled by default in favor of a system which will infer the correct vehicle and order the results by likelihood of behind correct.

featuresstringOptional

Comma separated list of additional registration lookup data codes, if using (e.g. additional_upstream_data)

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

successbooleanOptionalDefault: true

idstringOptional

regionstring · enumOptionalPossible values:

titlestringOptional

yearnumberOptional

makestringOptional

modelstringOptional

badgestringOptional

seriesstringOptional

body_typestringOptional

body_configstringOptional

transmissionstringOptional

wheelbasestringOptional

fuelstringOptional

enginestringOptional

drivestringOptional

num_doorsnumberOptional

upstream_vehiclestringOptional

The raw vehicle description. It is recommended that end users manually verify that this value corresponds to the same vehicle type as the "vehicle" object above.

confidencestring · enumOptional

The confidence that the vehicle was matched correctly. If this is 'reduced', it's recommended to manually check or prompt your end user to check if the vehicle is correct.

Possible values:

colourstringOptional

The colour of the vehicle, if known

vinstringOptional

The VIN of the vehicle, if known

idstringOptional

regionstring · enumOptionalPossible values:

titlestringOptional

yearnumberOptional

makestringOptional

modelstringOptional

badgestringOptional

seriesstringOptional

body_typestringOptional

body_configstringOptional

transmissionstringOptional

wheelbasestringOptional

fuelstringOptional

enginestringOptional

drivestringOptional

num_doorsnumberOptional

extended_dataanyOptional

Extended Data vehicle description product which can be selected by providing the appropriate query parameter

expiry_datestringOptional

statusstringOptional

compliance_platestringOptional

year_of_manufacturenumberOptional

writeoff_infoobject · WriteoffInfoProductOptional

vinstringOptional

build_datestringOptional

makestringOptional

modelstringOptional

codestringOptional

valuestringOptional

read_datestringOptional

ISO 8601 odometer read date

odometernumberOptional

predictionnumberOptional

days_since_readnumberOptional

avg_yearlynumberOptional

avg_dailynumberOptional

ag_market_avgnumberOptional

star_ratingnumberOptional

consumptionnumberOptional

co2numberOptional

star_ratingnumberOptional

test_regimestringOptional

star_ratingnumberOptional

test_regimestringOptional

400

Bad Request

application/json

errorbooleanOptionalDefault: true

messagestringOptional

Error message

401

Unauthorized

application/json

errorbooleanOptionalDefault: true

messagestringOptional

Error message

404

Not Found

application/json

errorbooleanOptionalDefault: true

messagestringOptional

Error message

get/v2/vehicles/registrations/{plate_number}

GET /v2/vehicles/registrations/{plate_number} HTTP/1.1
Host: api.autograb.com.au
ApiKey: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "vehicle": {
    "id": "text",
    "region": "au",
    "title": "text",
    "year": 1,
    "make": "text",
    "model": "text",
    "badge": "text",
    "series": "text",
    "body_type": "text",
    "body_config": "text",
    "transmission": "text",
    "wheelbase": "text",
    "fuel": "text",
    "engine": "text",
    "drive": "text",
    "num_doors": 1
  },
  "upstream_vehicle": "text",
  "confidence": "standard",
  "colour": "text",
  "vin": "text",
  "additional_vehicles": [
    {
      "id": "text",
      "region": "au",
      "title": "text",
      "year": 1,
      "make": "text",
      "model": "text",
      "badge": "text",
      "series": "text",
      "body_type": "text",
      "body_config": "text",
      "transmission": "text",
      "wheelbase": "text",
      "fuel": "text",
      "engine": "text",
      "drive": "text",
      "num_doors": 1
    }
  ],
  "extended_data": null,
  "registration_status": {
    "expiry_date": "text",
    "status": "text"
  },
  "vehicle_age": {
    "compliance_plate": "text",
    "year_of_manufacture": 1
  },
  "writeoff_info": {},
  "build_data": {
    "vin": "text",
    "build_date": "text",
    "make": "text",
    "model": "text",
    "features": [
      {
        "code": "text",
        "value": "text"
      }
    ]
  },
  "odo_history": [
    {
      "read_date": "text",
      "odometer": 1
    }
  ],
  "odo_prediction": {
    "prediction": 1,
    "days_since_read": 1,
    "avg_yearly": 1,
    "avg_daily": 1,
    "ag_market_avg": 1
  },
  "vsrr": {
    "fuel_economy": {
      "star_rating": 1,
      "consumption": 1
    },
    "emissions": {
      "co2": 1,
      "star_rating": 1
    },
    "pollutants": {
      "star_rating": 1,
      "test_regime": "text"
    },
    "safety": {
      "driver": {
        "star_rating": 1,
        "test_regime": "text"
      }
    }
  }
}

post

Value a vehicle using an AutoGrab ID

Authorizations

ApiKeystringRequired

Body

regionstring · enumOptionalPossible values:

vehicle_idstringRequired

The AutoGrab Vehicle ID which corresponds to the vehicle that should be valued

kmsnumberOptional

The odometer reading of the vehicle. If no reading is provided, the average value will be subsituted

rrp_overwritenumberOptional

rrp_adjustmentnumberOptional

condition_scorenumberOptional

regostringOptional

The registration plate of the vehicle, for reference purposes only

statestringOptional

The registration state of the vehicle, if applicable

vinstringOptional

The VIN of the vehicle, for reference purposes only

Responses

200

Success

application/json

successbooleanOptionalDefault: true

idstringOptional

The unique pricing record ID

vehicle_idstringOptional

The Vehicle ID of the vehicle that was priced

created_atstringOptional

The date when the preidction was made

kmsnumberOptional

The odometer reading that the valuation is based off. This is usually the same as the input provided, but if no odometer reading was specified, the average reading for the vehicle provided will be used instead.

pricenumberOptional

The predicted retail price

scorenumberOptional

The pricing confidence score. This indicates the estimated degree of accuracy for the price prediction.

retail_pricenumberOptional

The predicted retail price

trade_pricenumberOptional

The predicted trade price

vehicle_idstringOptional

typestring · enumOptional

The granularity of the price adjustment. Vehicle price adjustments are applied to the whole vehicle and set using /valuations/adjustments, whereas pricing_record adjustments are set for a specific record using /valuations/history.

Possible values:

enabledbooleanOptional

If the adjustment is enabled, it will be applied to new pricing requests for the vehicle id

amountnumberOptional

The value

typestring · enumOptional

Determines if the value is a percentage of a total value or a fixed amount

Possible values:

amountnumberOptional

The value

typestring · enumOptional

Determines if the value is a percentage of a total value or a fixed amount

Possible values:

idstringOptional

A unique ID that identifies the price override

min_kmsnumberOptional

The minimum odometer reading that this override will apply at

max_kmsnumberOptional

The maximum odometer reading that this override will apply at

trade_pricenumberOptional

The trade price override, if applicable

retail_pricenumberOptional

The retail price override, if applicable

lowernumberOptional

The predicted lower retail price bound

uppernumberOptional

The predicted upper retail price bound

lowernumberOptional

The predicted lower trade price bound

uppernumberOptional

The predicted upper trade price bound

reconditioningnumberOptional

profit_marginnumberOptional

lotnumberOptional

transportnumberOptional

adminnumberOptional

pricenumberOptional

400

Bad Request

application/json

errorbooleanOptionalDefault: true

messagestringOptional

Error message

401

Unauthorized

application/json

errorbooleanOptionalDefault: true

messagestringOptional

Error message

post/v2/valuations/predict

POST /v2/valuations/predict HTTP/1.1
Host: api.autograb.com.au
ApiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "region": "au",
  "vehicle_id": "text",
  "kms": 1,
  "rrp_overwrite": 1,
  "rrp_adjustment": 1,
  "condition_score": 1,
  "rego": "text",
  "state": "text",
  "vin": "text"
}

{
  "success": true,
  "prediction": {
    "id": "text",
    "vehicle_id": "text",
    "created_at": "text",
    "kms": 1,
    "price": 1,
    "score": 1,
    "retail_price": 1,
    "trade_price": 1,
    "adjustment": {
      "vehicle_id": "text",
      "type": "account",
      "enabled": true,
      "trade_adjustment": {
        "amount": 1,
        "type": "fixed"
      },
      "retail_adjustment": {
        "amount": 1,
        "type": "fixed"
      },
      "overrides": [
        {
          "id": "text",
          "min_kms": 1,
          "max_kms": 1,
          "trade_price": 1,
          "retail_price": 1
        }
      ]
    }
  },
  "bounds": {
    "retail": {
      "lower": 1,
      "upper": 1
    },
    "trade": {
      "lower": 1,
      "upper": 1
    }
  },
  "max_offer": {
    "reconditioning": 1,
    "profit_margin": 1,
    "lot": 1,
    "transport": 1,
    "admin": 1,
    "price": 1
  }
}

Recapture API

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
- state: The registration state of the vehicle, if applicable

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:

Webhooks

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

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

This API requires authentication and 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 AutoGrab 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 (au)
format

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=au 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 a 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.

🇲🇾 MY AutoGrab API Doc

AutoGrab Basics

AutoGrab Developer Hub

Integration Overview

Overview

Environments

Regions

API Test Cases

Test Cases

FAQ

Authentication

API Key

Key Types

Secret API Key

Public API Key

Authenticating Requests

Other Authentication Methods

OAuth Authentication

Vehicle Search

Vehicle Searching Basics

Plain-text Search

Registration Plate Search

Overview

Features

Extended Data

Upstream Data

Vehicle ID Search

Marketplace ID Lookup

Sourcing

Sourcing Basics

Market Statistics

Stock Feeds

Creating a stock feed

Stock item schema

Posting stock items

Vehicle Data

Vehicle Data Basics

Valuation

Valuation Basics

Residual Valuations

Max Offer Configuration

Gauge API

Example Post Body

Use Case Driven Implementation Examples

Marketplace Implementation

Dealer Website Implementation (AutoGrab Customer)

Dealer Website Implementation (Non-Direct Customer)

Embeddable Products

Embeddable Basics

Valuation Widget

REPORTS

Car Analysis

Report Features

Vehicle Identification

Valuation

Price Record ID

Lead ID

Odometer

Sources

Recapture

Insurance

Pre-Accident Valuation

Workflow Overview

Isolate The Vehicle ID

AutoGrab Developer Hub

Plain-text Search

Example

Stock Feeds

Creating a stock feed

Stock item schema

Posting stock items

Search for a vehicle with a query string

API Key

Key Types

Secret API Key

Public API Key

Authenticating Requests

Other Authentication Methods

Integration Overview

Overview