API reference
A private, token-authenticated API for pulling your estate into your own systems. It reads the same
data the RAAD console reads, so a device that has just reported in is available here immediately.
Send Authorization: Bearer <token> with every request. Every response is
{ data }, plus { page } on paginated lists, and errors are
{ error: { code, message } }.
The contract itself is private. openapi.json and the interactive console both require a
partner or platform session, so open them in a tab where you are already signed in to the portal.
Every device carries an iccid. RAAD reports what that SIM is doing beside the asset it
is fitted to, so a device that has been switched off can be told apart from one that has lost signal.
Authentication
One header, on every request.
Tokens are issued in Settings → API inside the portal. A token belongs to one tenant and carries a fixed set of scopes, so the safest pattern is one token per integration with only the scopes that integration needs. The token is shown once at creation. Store it as a secret and rotate it by issuing a new one, then revoking the old.
Send the token in the Authorization header. Query-string tokens are not accepted, and a
request with no header, an expired token or a revoked token returns 401. Call
/health to confirm which tenant and scopes a token is acting as before you wire anything
else up.
Scopes
One read scope per area. A token carries only the ones its integration needs.
A token that lacks the scope an endpoint requires gets 403, not an empty list, so a
permissions problem never looks like missing data. Scopes are additive and set when the token is issued.
/devices and /devices/{id}./positions, /positions/history, /sensors and /geofences./events, /incidents and /rules./assets and /assets/{id}./drivers./documents./maintenance./power./meters./sense./guard/cases./cam/clips./carbon./reports./support/cases.
/health requires no scope beyond a valid token, which makes it the right endpoint for an
uptime check or a credential test.
Errors and limits
One error shape, whatever went wrong.
{ data }, plus { page } on paginated lists./positions/history when deviceId, from or to is absent or unparseable.Rate limiting
Requests are limited per token. Poll /positions rather than looping over
/devices/{id}, and page through /events with a cursor rather than re-reading
the head of the list. If you need a higher ceiling for a bulk export, ask before you build against it.
Pagination
Cursor-based, on every list that grows without bound.
Registry-style lists (/devices, /positions, /rules, /meters
and the like) return everything the token may see in one call. Logs and ledgers grow without bound, so
/events, /incidents, /documents, meter readings, sense readings,
clips, carbon entries, report runs and cases are paginated. Each returns newest first, up to
limit rows, with page.nextCursor set when more remain. Pass that value back as
cursor to continue. When nextCursor is null you have reached the
end. An endpoint that paginates says so in its header, and takes the same two parameters.
Store the newest id you have processed rather than a timestamp. Events are written as they
are evaluated, and a device that reconnects after a gap can backfill events with older
occurredAt values than ones you have already seen.
Endpoints
Thirty endpoints, all read-only in v1. Select one to see its parameters, a request in three languages and a real response.
System
Confirm a token works and see what it can reach.
Returns the tenant and scopes this token acts as. Accepts any valid token, so it doubles as a health check and as the first call to make when an integration starts returning 403.
Request
Response
Devices
The registry: what is onboarded, what state it is in, and which SIM it is on.
Every device this token may see, with its current state and the time it last reported. Returns the whole set rather than a page, so cache it and refresh on a schedule rather than per request.
Request
Response
Notes
state is one of moving, idle, stopped,
offline or nodata. nodata means the device is registered
but has never reported; offline means it has reported before and has now gone quiet.
protocol names the decoder handling the device, one of 267 supported.
One device with its latest status and telemetry.
Path parameters
deviceId from /devices. Not the uniqueId printed on the hardware.Request
Response
Positions
Where everything is now, and where one thing has been.
The latest position of every device this token may see. This is the endpoint to poll for a live map: one call returns the whole estate, so you never need to fan out per device.
Request
Response
Notes
lastFix is when the GPS fix was taken; lastUpdate is when the platform
received it. A device inside a tunnel or a container reports a fresh lastUpdate
against a stale lastFix. Treat a widening gap between the two as loss of GPS rather
than loss of the device. lat and lon are null until the first fix.
Movement history for one device over a time range, already segmented into trips and stops with a summary. You do not have to reconstruct journeys from raw points.
Query parameters
Z suffix.Request
Response
Sensors
Configured sensors and their latest values, per device.
Every configured sensor on every device this token may see, with the most recent reading. Values are already calibrated, so a fuel probe reads in litres rather than in raw counts.
Request
Response
Events
Rule fires and device events, newest first.
Everything the platform has raised against a device: rule fires and events reported by the hardware itself. Newest first, cursor-paginated. This is the feed to mirror into a ticketing system or a warehouse.
Query parameters
100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
severity is one of critical, warning, info or
muted. muted events are suppressed in the console but still returned
here, so filter on it if you are mirroring the operator's worklist rather than the full log.
page.nextCursor is null on the last page.
Geofences
The tenant's zones, with geometry you can draw.
Every zone on the tenant, with geometry already parsed. Pair it with /positions to render the same map the console shows.
Request
Response
Notes
Coordinates are [longitude, latitude], matching GeoJSON. That is the reverse of the
lat/lon fields on a position, so check the order before you plot.
radius is in metres. A polygon is not closed for you; repeat the first point if your
renderer needs it.
Assets
The things your customers manage, as opposed to the hardware fitted to them.
Every asset this token may see, with the class-specific attributes bag for its type. A device is the hardware; an asset is the truck, trailer, container or site it reports on, and this is the list your own systems key on.
Query parameters
truck, trailer, container, site or fridge.active, maintenance or retired.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
mobility is derived from the type: mobile for vehicles, trailers and containers, fixed for sites, buildings, rooms, fridges and cabinets. The keys inside attributes depend on the type, so read them as a bag rather than a fixed shape.
One asset with the driver assigned to it and the devices linked to it. This is the join between the asset world and the device world: start here to find which deviceId to pass to /positions/history.
Path parameters
id from /assets.Request
Response
Drivers
Who is behind the wheel, and where each one is in onboarding.
The tenant's drivers with contact details, licence number and onboarding stage. The stage is computed from the documents on file, so a driver whose insurance lapses drops out of ready without anyone editing the record.
Query parameters
draft, invited, in_review, ready, suspended or archived.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
suspended and archived are set by hand and stay put; every other stage is recomputed whenever a document changes or expires. status is kept for compatibility and no longer drives anything. Use stage.
Compliance
Documents and their expiry dates, without the file bytes.
Document metadata for the tenant, soonest expiry first. Rejected uploads are left out. Each row tells you what the document is, who or what it belongs to and when it runs out; the file itself is not served over the API.
Query parameters
insurance, licence, photo or a type your tenant has configured.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
A document belongs to either an asset or a driver, so one of assetId and driverId is set. To build an expiry feed, page through with limit=500 and stop when expiryDate is later than your horizon; the list is already in that order.
Maintenance
Service, inspection and repair tasks against assets.
Maintenance tasks, soonest due first. A task is due on a date, at an odometer reading, or both, so a service that is booked for next month can still come due early on a hard-working truck.
Query parameters
scheduled, done or cancelled.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
kind is service, inspection, repair or other. cost is in the tenant's billing currency and is only filled in once a task is done.
Incidents and rules
Alerts rolled up into incidents, and the rules that raise them.
Alerts grouped into incidents. A fuel sensor that trips forty times in a night is one incident with count: 40, not forty rows, so this is the feed to drive a ticketing or on-call system from. /events stays the raw log underneath.
Query parameters
open, acknowledged, snoozed or resolved.tracking, fuel, meter or sense.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
Newest activity first, ordered by lastAt. Exactly one of deviceId, assetId, meterId or packId names the subject, depending on the module.
Every alerting rule configured for the tenant, across all modules: what it watches, the threshold, the severity it raises at, which devices or groups it applies to and whether it is switched on. Read this to explain an incident, or to audit what a customer is actually monitoring.
Request
Response
Notes
A rule with empty deviceIds and groupIds applies to the whole tenant. The shape of threshold depends on trigger.
Power
Fuel and electricity on one ledger, plus packs, cabinets and the forecourt.
The unified energy ledger, newest first. Every fill, charge, swap and sale lands here as one row with a quantity, a unit and an amount, whether the resource was diesel or kilowatt-hours. Reconcile a fuel card or a charging bill against it.
Query parameters
100, capped at 500.Request
Response
Notes
kind is swap, sale, charge or fill. direction is in for energy bought and out for energy sold or dispensed, so summing amount by direction gives cost and revenue.
Every battery pack in the estate with its state of charge, state of health and where it is: in the field, in a cabinet, charging, flagged or retired.
Request
Response
Notes
This returns the full pack record, so expect more fields than shown as the model grows. The ones above are stable. status is in_field, in_cabinet, charging, flagged or retired.
Swap cabinets with live bay occupancy, and the forecourt if the tenant runs one: pumps and chargers with today's throughput. One call gives a wall display everything it needs.
Request
Response
Notes
forecourt is null for a tenant that has no dispensing points. Cabinet counts (ready, charging, fault) add up to occupied bays; the remainder of bays is empty.
Energy throughput, cost and revenue over a trailing window, with the indicative carbon figures the ESG module derives from it. The numbers a monthly report opens with.
Query parameters
30, capped at 365.Request
Response
Notes
scope2Kg is the emissions from charging; avoidedKg is the combustion those swaps displaced. Both are indicative and use the same factors as /carbon/summary.
Meters
Smart meters, their reads and their prepaid top-ups.
Every smart meter with its supply state, prepaid balance and when it last reported. Where the platform could fetch fresh state from the meter engine for this call, live is true.
Request
Response
Notes
relayState is connected, disconnected or unknown. A meter with a zero balance and a disconnected relay has been cut off for non-payment; a top-up reconnects it. status is enrolled, offline or fault.
Interval reads for one meter, newest first. Each row is one OBIS register at one timestamp, so a meter reporting import energy and instantaneous power produces two rows per interval.
Path parameters
id from /meters.Query parameters
100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
1-0:1.8.0 is cumulative import energy in kWh; 1-0:1.7.0 is instantaneous import power in kW. Consumption over a period is the difference between two 1.8.0 reads.
Prepaid top-up history for one meter, newest first: how much was bought, by what route, whether the token reached the meter, and the UTRN where one was issued.
Path parameters
id from /meters.Query parameters
100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
status is pending, delivered or failed. operator names the console user for a manual top-up and is null for a customer payment.
Sense
Temperature, humidity and door sensors across fixed sites.
Every environmental sensor and the fixed place it watches: a fridge, a cold room, a site. Sensors talk over LoRaWAN, so they are identified by devEui rather than a deviceId.
Request
Response
Notes
place is null for a sensor that has been onboarded but not yet assigned to a place. capabilities says which metrics to expect from /sense/readings.
Environmental readings, newest first. Filter to one sensor and one metric to chart it; leave the filters off to mirror the whole stream.
Query parameters
id from /sense/places.temperature, humidity, door or battery.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
Units are degrees Celsius, percent relative humidity, 1 or 0 for a door (open or closed) and volts for battery.
Guard
Custody cases raised on locked assets.
Guard custody cases, newest first. A case opens when a locked asset does something it should not, such as leaving a geofence, losing telemetry or reporting tamper, and tracks what was done about it until it closes.
Query parameters
open, watch, drifting, action_pending, restricted, recovery or closed.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
classifier is what opened the case, for example geofence_exit, tamper, telemetry_gap or no_response. Lock and unlock commands are not exposed in v1.
Cam
Camera clips and driver-safety events, as metadata.
Camera clips and driver-safety (DSM) events, newest first. Metadata only: what was detected, on which camera channel, where and when, and whether the clip has been stored. The media itself is fetched in the console.
Query parameters
dsm_drowsiness, dsm_phone or dsm_distraction.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
kind is dsm_event, periodic or request; channel is driver (cab-facing) or road. traccarDeviceId is the camera's deviceId in /devices. status is pending, stored, failed or expired.
Carbon
Indicative Scope 1 and 2 emissions, by period and by activity.
Computed carbon footprints, one per reporting period: Scope 1 from fuel burned, Scope 2 from electricity drawn, and the total. What the ESG report prints.
Request
Response
Notes
status is computed (rolling, will change as the period fills), draft or final. Figures are indicative: they use published emission factors, not metered stack measurements.
The carbon ledger, newest first: each activity with the quantity it was measured in, the emission factor applied and where that factor came from. Enough to reproduce any footprint line by line.
Query parameters
1 for direct combustion or 2 for purchased electricity. Anything else returns both.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
Emissions for a row are quantity × factorValue in kg CO₂e. factorValue is null where no factor has been assigned yet, and such rows are excluded from /carbon/summary.
Reports
Report runs that have finished, with their headline metrics.
Completed report runs, newest first. Every report a user runs or schedules in the console is kept as a durable artifact with the parameters it ran with and its headline metrics, so you can pick up a nightly trips report without re-running it.
Query parameters
100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
key is the report type: trips, stops, summary, route, events, geofence or rule_alerts. Only runs with status: done are listed. The rows themselves are downloaded from the console.
Support
Faults and requests raised against the estate.
Support cases, newest first: the number a customer quotes on the phone, the category, priority, status and the SLA clock. Mirror this into your own desk so your team sees the same queue the console does.
Query parameters
new, in_progress, on_hold, resolved or closed.100, capped at 500.page.nextCursor from the previous response. Omit it for the first page.Request
Response
Notes
category is connectivity, device, platform or billing; type is fault or request; priority runs P1 to P4. slaDueAt is null once a case is resolved or where no SLA applies.
Schemas
Every object v1 returns, plus the error envelope.
Device
Returned by /devices and /devices/{id}.
moving, idle, stopped, offline or nodata.Position
Returned by /positions.
Event
Returned by /events.
fuelDrop or geofenceExit. Branch on this, not on label.critical, warning, info or muted.Geofence
Returned by /geofences.
circle or polygon. It determines the shape of geometry.{ center: [lon, lat], radius } with the radius in metres. A polygon is { points: [[lon, lat]] }.Asset
Returned by /assets.
/assets/{id}.truck, trailer, container, site, fridge.mobile or fixed, derived from the type.active, maintenance or retired.diesel, petrol, electric.AssetDetail
Returned by /assets/{id}.
{ id, name } of the assigned driver.{ deviceId, label, type }. deviceId is null for a device slot that is defined but not yet fitted.Driver
Returned by /drivers.
draft, invited, in_review, ready, suspended, archived. Computed from documents.Document
Returned by /documents.
insurance, licence, photo.active or pending. Rejected documents are not listed.MaintenanceTask
Returned by /maintenance.
service, inspection, repair or other.scheduled, done or cancelled.Incident
Returned by /incidents.
tracking, fuel, meter, sense.fuelDrop.critical, warning or info.open, acknowledged, snoozed or resolved.Rule
Returned by /rules.
fuelDrop, geofenceExit, speeding.PowerConsumptionRow
Returned by /power/consumption.
swap, sale, charge or fill.diesel, petrol, electricity and so on.in (bought) or out (sold or dispensed).L or kWh.logged, pending, reconciled, exception, disputed or dismissed.fuel_card, mpesa.Site
Returned by /power/sites.
online, degraded or offline.PowerSummary
Returned by /power/summary.
currency.Meter
Returned by /meters.
push or poll, and the address polled where relevant.connected, disconnected or unknown.enrolled, offline or fault.MeterReading
Returned by /meters/{id}/readings.
1-0:1.8.0.Topup
Returned by /meters/{id}/topups.
mpesa, card, manual.pending, delivered or failed.Place
Returned by /sense/places.
device to /sense/readings.{ assetId, name, type } of the place it monitors, or null if unassigned.SenseReading
Returned by /sense/readings.
temperature, humidity, door or battery.GuardCase
Returned by /guard/cases.
open, watch, drifting, action_pending, restricted, recovery or closed.critical, warning or info.geofence_exit, tamper, telemetry_gap.CamClip
Returned by /cam/clips.
deviceId.dsm_event, periodic or request.dsm_phone.driver or road.pending, stored, failed or expired.CarbonSummary
Returned by /carbon/summary.
computed, draft or final.CarbonEntry
Returned by /carbon/entries.
1 or 2.diesel, grid_electricity_ke.L or kWh.Report
Returned by /reports.
trips, stops, summary, route, events, geofence or rule_alerts.done in this list.SupportCase
Returned by /support/cases.
connectivity, device, platform or billing.fault or request.P1 to P4.new, in_progress, on_hold, resolved or closed.Error
Returned with every 4xx status.
unauthorized or forbidden. Branch on this.Webhooks and write endpoints are on the roadmap for v2. If you are building something that needs one of them, tell us what you are building and we will tell you where it sits.