Tractor Telemetry Push Specification

Push raw per-device telemetry from your platform to Hello Tractor. This is a one-way feed. Once data reaches us, our existing pipeline handles trip detection, fuel curves, summaries, alerts, geocoding, and downstream analytics.

Background

Your side only needs to send normalized telemetry events. If your tracking platform does not support pushing to external HTTPS endpoints directly, a common approach is a lightweight adapter that:

Pulls events from your source platform
Maps them to the schema below
POSTs to Hello Tractor

Connection

Field	Value
Method	`POST`
URL	Provided during collaboration onboarding
Auth	`Authorization: Bearer <token>` (provided during onboarding)
Content-Type	`application/json`
Encoding	`UTF-8`
TLS	Required (`HTTPS`)

Payload

The payload follows the CloudEvents 1.0 envelope convention.

Send one envelope per position update per device
The endpoint accepts either a single JSON object or an array of envelopes

{
  "specversion": "1.0",
  "id": "8d4a1f3e-7c2b-4e1a-9f8c-7e6d5b4a3c2d",
  "type": "<provided at onboarding>",
  "source": "<provided at onboarding>",
  "operation": "upsert",
  "time": "2026-05-28T14:23:11.482Z",
  "serviceaccount": "<provided at onboarding>",
  "data": {
    "deviceId": "352093089123456",
    "assetUid": "f3e2a1b4-9c8d-4e5f-a6b7-c8d9e0f1a2b3",
    "assetId": "TR-AZ-00142",
    "accountId": "az-partner-001",
    "locationTime": 1748441000000,
    "eventTime": 1748441002150,
    "latitude": 40.409262,
    "longitude": 49.867092,
    "altitude": 28.0,
    "heading": 178.5,
    "speed": 12.4,
    "deviceStatus": "moving",
    "engineState": "ON",
    "deviceBatteryVoltage": 12480,
    "assetBatteryVoltage": 12190,
    "fuelRawValue": 3420
  }
}

Field reference

Envelope (CloudEvents)

Field	Type	Required	Notes
`specversion`	string	Yes	Always `1.0`
`id`	string	Yes	Unique per event. UUIDv4 recommended. Must remain stable across retries for deduplication
`type`	string	Yes	Constant value provided during onboarding
`source`	string	Yes	Constant value provided during onboarding (identifies your source)
`operation`	string	Yes	Always `upsert` for position updates
`time`	string	Yes	RFC3339 UTC timestamp when your system emitted the event
`serviceaccount`	string	Yes	Constant value provided during onboarding
`data`	object	Yes	Telemetry payload described below

Data fields (required)

Field	Type	Notes
`deviceId`	string	Unique stable tracker ID (IMEI works well)
`assetUid`	string	Unique stable tractor ID. UUID preferred. If not separated, use same value as `deviceId`
`assetId`	string	Human-readable tractor/business identifier
`accountId`	string	Customer/account owner identifier
`locationTime`	int64	GPS fix timestamp, Unix epoch milliseconds UTC
`eventTime`	int64	Event receive timestamp in your platform, Unix epoch milliseconds UTC. Use `locationTime` if unavailable
`latitude`	float	Decimal degrees, range `-90` to `90`
`longitude`	float	Decimal degrees, range `-180` to `180`
`heading`	float	Degrees `0` to `360` (`0` = North). Send `0` if unknown
`speed`	float	Ground speed in km/h, `>= 0`
`deviceStatus`	string enum	One of `stopped` or `moving`. If derived, use `moving` when speed `> 1 km/h`
`engineState`	string enum	One of `ON` or `OFF`, sourced from ignition signal

Data fields (optional)

Send these when available; omit otherwise.

Field	Type	Notes
`altitude`	float	Meters above sea level
`deviceBatteryVoltage`	float	Tracker internal battery in millivolts
`assetBatteryVoltage`	float	Tractor main battery in millivolts
`fuelRawValue`	float	Raw fuel sensor value (analog mV or CAN/SPN). Do not pre-convert to liters

Batching

To reduce HTTP overhead, send up to 500 events per request:

[
  { "specversion": "1.0", "id": "...", "data": { "...": "..." } },
  { "specversion": "1.0", "id": "...", "data": { "...": "..." } }
]

The endpoint accepts both single-object and array bodies. Elements are validated independently: malformed events are rejected individually, while valid events are accepted.

Share your source platform, event model, and expected volume with the integration team. We will provide the endpoint URL, token, type, source, and serviceaccount values for your rollout.

Get started

Tell us what you are building and we will align on API access and telemetry integration.