Data Model

A handful of core concepts run through the entire Destiny API. Getting these right up front will save you a lot of confusion.

Units vs Vehicles — the key distinction

These are not the same thing, and the API keeps them separate on purpose:

• A Unit is a physical tracking device (hardware) with its own identifiers — IMEI, serial number, type and model.
• A Vehicle is the asset being tracked (a truck, car, trailer, asset).

A Unit is allocated to a Vehicle. Hardware can be swapped, repaired, scrapped or transferred between vehicles and clients without losing the vehicle's history — which is why the API has a dedicated Unit Swapping and Unit Transfer set of operations, separate from creating or editing the vehicle itself.

tip

When you query telemetry, you can address it by Unit (/units/.../telemetry, or by IMEI / serial number) or by Vehicle (/vehicles/.../telemetry). Pick the one that matches what you actually hold a reference to.

Organisational hierarchy

Records are scoped through an ownership hierarchy. Most list and permission endpoints accept partner_id, agency_id and/or client_id to scope results:

Partner ─▶ Agency ─▶ Client ─▶ (Vehicles, Units, Drivers, ...)

• Partner — top-level reseller / operator.
• Agency — an optional layer beneath a partner.
• Client — the end customer who owns vehicles and drivers.

Grouping

Both units and vehicles can be organised into groups for bulk operations and reporting:

• Unit Groups — collections of units.
• Vehicle Groups — collections of vehicles (used heavily by reports and status views).

Other primary resources

Resource	Description
Drivers	People who operate vehicles; can be monitored and reported on.
Event Profiles	Define which events are monitored per client/channel.
Reports	Generated asynchronously (PDF) — you request a run, then poll for status.
Dashboards / Widgets	User-configurable dashboard layouts.
Sensors	Telemetry inputs, defined per unit type and model.

See the full set under the API Reference.