Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

How the EROAD integration works: API keys, sensor alerts and data shared

This article explains how GetHomeSafe connects to EROAD, what each API key does, and what data moves between the two systems. Use it when you’re setting up the integration, deciding whether you need the optional key, or answering a security or privacy review.

Overview

The integration uses two separate EROAD APIs, and each one needs its own key:

Key Required? What it’s used for
Gateway Partner API key Yes Listing fleets, importing vehicles, polling vehicle location, and driver sync
Integration API key No Crash detection (CARA) and panic alerts from the EROAD unit’s sensor inputs

Gateway Partner API key (required)

This key runs the core of the integration. We use it to:

  • List your fleets
  • Import vehicles
  • Poll each vehicle’s current state (GPS location, speed, heading and timestamp)
  • Look up the current driver for driver sync

Note: The integration won’t work without this key.

Integration API key (optional)

This key gives us access to EROAD’s newer Integration API, which includes the Historical Event endpoint. We only use it for sensor input alerts (see below).

On the enterprise settings page, this is the Integration Api Key field. You can leave it blank if you don’t need sensor alerts.

How sensor input alerts work

Tip: Vehicle locations don’t come from the Historical Event API. They come from the Gateway Partner API’s current state endpoint.

The Historical Event API has one job: detecting changes to the digital sensor inputs on the EROAD unit so GetHomeSafe can raise alerts.

  1. When you save an Integration API key, we call EROAD’s introspect endpoint once. This gets your EROAD organisation ID and checks that the key has the Machine Management and Historical Event permissions.
  2. On each poll, we query the Historical Event endpoint for every vehicle assigned in GetHomeSafe. Each query covers only the time since our last check, and we request only the DIGITAL_SENSOR_INPUT_CHANGE event type.
  3. When a sensor input turns ON and its number matches your configured CARA (crash detection) input or panic alert input, we raise a GetHomeSafe panic alert against that vehicle’s activity.

Data shared between GetHomeSafe and EROAD from (Optional) Intergration API Permissions

Sent to EROAD

  • EROAD organisation ID
  • EROAD vehicle ID
  • Start time and duration (in minutes)
  • Event type filter

Received from EROAD

  • Event ID and event type
  • Timestamp
  • Sensor number and sensor status
  • Position and speed at the time of the event

We only act on the sensor fields. The only things we keep are the alert that gets created and a short-lived cache of processed event IDs, which stops the same alert being raised twice.