FleetLive Partner API

Quick start

From zero to your first call in three steps

Authenticate once with client-credentials, then call any endpoint with a bearer token. Your organization context comes from the token, so there is no org header to manage.

Get credentials

Create a client on your organization’s API Access page. You receive a client_id and a one-time client_secret.

org · api access

FLEETLIVE_CLIENT_ID="cl_7Q2f9a1b8e4c"
FLEETLIVE_CLIENT_SECRET="sk_live_shown_once"

Get a token

Exchange the credentials at FleetLive Identity for a bearer token scoped to partner.api.

POST · identity.fleetlive.ai

curl -X POST https://identity.fleetlive.ai/connect/token \
  -d grant_type=client_credentials \
  -d client_id=$FLEETLIVE_CLIENT_ID \
  -d client_secret=$FLEETLIVE_CLIENT_SECRET \
  -d audience=partner.api \
  -d scope=partner.api

Make your first call

Send the token as a bearer header. Here we list vehicles in your fleet, with the org resolved from the token’s fleetlive.org_id claim.

GET · api.partner.fleetlive.ai

curl https://api.partner.fleetlive.ai/v1/vehicles \
  -H "Authorization: Bearer $TOKEN"

# 200 OK
# { "items": [ { "id": "veh_a91f", "reg": "BX21 LMC",
#   "fleetId": "flt_north", "status": "moving" } ], ... }

Webhook events

Every event we deliver, and the exact body

Subscribe an endpoint and FleetLive posts a signed JSON body when something happens on a vehicle. Each delivery is a FleetLiveWebhookEvent envelope with a stable eventId for dedupe, the topic type, your organisationId, an occurredAt timestamp, and a per-topic data payload.

Signing and delivery live in HTTP headers, not the body: X-FleetLive-Signature (HMAC-SHA256, t=<unix>,v1=<hex>), FL-Delivery (delivery id), FL-Event (topic name). Acknowledge with any 2XX; anything else is retried with backoff. Dedupe on eventId.

journey.completed A journey finished (or a correction to one already sent, flagged by isUpdated) with distance, timings, addresses and start/end positions.

envelope + payload

{
  "eventId": "9f2c0b7a-4e11-4d3a-8a6e-2b1c9d0e5f31",
  "type": "journey.completed",
  "organisationId": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
  "occurredAt": "2026-07-09T14:32:08Z",
  "data": {
    "journeyId": "1a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b",
    "isUpdated": false,
    "startAddress": "12 Dock Rd, Liverpool",
    "endAddress": "Trafford Park, Manchester",
    "startTime": "2026-07-09T13:05:00Z",
    "endTime": "2026-07-09T14:32:08Z",
    "lengthMeters": 58120.4,
    "timeInSeconds": 5228,
    "maxSpeed": 96,
    "idleTimeInSeconds": 214,
    "startLocation": { "lat": 53.4084, "long": -2.9916 },
    "endLocation": { "lat": 53.4670, "long": -2.3210 },
    "device": { "hardwareId": "SMX-8841207" },
    "organisation": { "id": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d" },
    "fleet": { "id": "6d5c4b3a-2f1e-4d0c-8b7a-9e0f1a2b3c4d" },
    "vehicle": { "id": "c4d3e2f1-0a9b-4c8d-7e6f-5a4b3c2d1e0f" }
  }
}

alarm.raised A safety alarm fired. The kind is carried in alarmKey (for example harshBraking), with the location, speed and heading at trigger time.

envelope + payload

{
  "eventId": "5c7d8e9f-0a1b-4c2d-3e4f-5a6b7c8d9e0f",
  "type": "alarm.raised",
  "organisationId": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
  "occurredAt": "2026-07-09T14:33:51Z",
  "data": {
    "id": "alm_7f31c9",
    "triggerTime": "2026-07-09T14:33:51Z",
    "alarmKey": "harshBraking",
    "location": { "lat": 53.4661, "long": -2.3402 },
    "speed": 47,
    "heading": 118,
    "alarmState": 1,
    "ioNumber": null,
    "device": { "hardwareId": "SMX-8841207" },
    "organisation": { "id": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d" },
    "fleet": { "id": "6d5c4b3a-2f1e-4d0c-8b7a-9e0f1a2b3c4d" },
    "vehicle": { "id": "c4d3e2f1-0a9b-4c8d-7e6f-5a4b3c2d1e0f" }
  }
}

device.event One or more device events occurred, listed in eventTypes as canonical dotted tokens (for example dsm.fatigue). Always at least one; never empty.

envelope + payload

{
  "eventId": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70819",
  "type": "device.event",
  "organisationId": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
  "occurredAt": "2026-07-09T14:34:12Z",
  "data": {
    "id": "evt_9a2f10",
    "triggerTime": "2026-07-09T14:34:12Z",
    "eventTypes": [ "dsm.distraction", "dsm.fatigue" ],
    "device": { "hardwareId": "SMX-8841207" },
    "organisation": { "id": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d" },
    "fleet": { "id": "6d5c4b3a-2f1e-4d0c-8b7a-9e0f1a2b3c4d" },
    "vehicle": { "id": "c4d3e2f1-0a9b-4c8d-7e6f-5a4b3c2d1e0f" }
  }
}

media.available Requested MDVR video is ready to fetch. type maps to the media purpose, and event links the event it was pulled for. Org is in the envelope only.

envelope + payload

{
  "eventId": "7e8f9a0b-1c2d-4e3f-5a6b-7c8d9e0f1a2b",
  "type": "media.available",
  "organisationId": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
  "occurredAt": "2026-07-09T14:40:03Z",
  "data": {
    "id": "0f1e2d3c-4b5a-4968-8776-5544332211ff",
    "type": 2,
    "device": { "hardwareId": "SMX-8841207" },
    "event": { "id": "9a2f10bc-7d6e-4f5a-8b9c-0d1e2f3a4b5c" },
    "fleet": { "id": "6d5c4b3a-2f1e-4d0c-8b7a-9e0f1a2b3c4d" },
    "vehicle": { "id": "c4d3e2f1-0a9b-4c8d-7e6f-5a4b3c2d1e0f" }
  }
}

live-gps A live position fix as it lands: fix time, speed, heading and location. The eventId is {hardwareId}:{utc} so replays are naturally idempotent.

envelope + payload

{
  "eventId": "SMX-8841207:2026-07-09T14:41:07.4210000Z",
  "type": "live-gps",
  "organisationId": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
  "occurredAt": "2026-07-09T14:41:07.421Z",
  "data": {
    "utc": "2026-07-09T14:41:07.421Z",
    "speed": 52.4,
    "heading": 121.8,
    "location": { "lat": 53.4655, "long": -2.3450 },
    "device": { "hardwareId": "SMX-8841207" },
    "organisation": { "id": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d" },
    "fleet": { "id": "6d5c4b3a-2f1e-4d0c-8b7a-9e0f1a2b3c4d" },
    "vehicle": { "id": "c4d3e2f1-0a9b-4c8d-7e6f-5a4b3c2d1e0f" }
  }
}

telemetry-raw A batch of raw telemetry frames for one device over a short window, ascending by time. Best-effort delivery with possible duplicates, so dedupe on eventId.

envelope + payload

{
  "eventId": "SMX-8841207:2026-07-09T14:30:00Z:0:3f9a1c",
  "type": "telemetry-raw",
  "organisationId": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
  "occurredAt": "2026-07-09T14:45:00Z",
  "data": {
    "device": { "hardwareId": "SMX-8841207" },
    "organisation": { "id": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d" },
    "fleet": { "id": "6d5c4b3a-2f1e-4d0c-8b7a-9e0f1a2b3c4d" },
    "vehicle": { "id": "c4d3e2f1-0a9b-4c8d-7e6f-5a4b3c2d1e0f" },
    "windowStart": "2026-07-09T14:30:00Z",
    "windowEnd": "2026-07-09T14:45:00Z",
    "count": 3,
    "historic": false,
    "frames": [
      { "utc": "2026-07-09T14:30:00Z", "location": { "lat": 53.4084, "long": -2.9916 }, "speed": 48, "heading": 117, "signal": true },
      { "utc": "2026-07-09T14:37:30Z", "location": { "lat": 53.4370, "long": -2.6620 }, "speed": 61, "heading": 104, "signal": true },
      { "utc": "2026-07-09T14:45:00Z", "location": { "lat": 53.4655, "long": -2.3450 }, "speed": 52, "heading": 122, "signal": false }
    ]
  }
}

geofence.entered A vehicle entered a geofence. Carries the geofence id and name snapshot, the crossing position, and the interpolated crossing time. Consume idempotently.

envelope + payload

{
  "eventId": "4d5e6f70-8192-43a4-b5c6-d7e8f9001a2b",
  "type": "geofence.entered",
  "organisationId": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
  "occurredAt": "2026-07-09T14:50:20Z",
  "data": {
    "id": "4d5e6f70-8192-43a4-b5c6-d7e8f9001a2b",
    "occurredAt": "2026-07-09T14:50:20Z",
    "geofence": { "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071", "name": "Trafford Park Depot" },
    "position": { "lat": 53.4668, "long": -2.3195 },
    "device": { "hardwareId": "SMX-8841207" },
    "organisation": { "id": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d" },
    "fleet": { "id": "6d5c4b3a-2f1e-4d0c-8b7a-9e0f1a2b3c4d" },
    "vehicle": { "id": "c4d3e2f1-0a9b-4c8d-7e6f-5a4b3c2d1e0f" }
  }
}

geofence.exited A vehicle left a geofence. Identical shape to geofence.entered, with the exit position and interpolated crossing time.

envelope + payload

{
  "eventId": "5e6f7081-9243-44b5-c6d7-e8f9001a2b3c",
  "type": "geofence.exited",
  "organisationId": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
  "occurredAt": "2026-07-09T15:12:44Z",
  "data": {
    "id": "5e6f7081-9243-44b5-c6d7-e8f9001a2b3c",
    "occurredAt": "2026-07-09T15:12:44Z",
    "geofence": { "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071", "name": "Trafford Park Depot" },
    "position": { "lat": 53.4655, "long": -2.3220 },
    "device": { "hardwareId": "SMX-8841207" },
    "organisation": { "id": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d" },
    "fleet": { "id": "6d5c4b3a-2f1e-4d0c-8b7a-9e0f1a2b3c4d" },
    "vehicle": { "id": "c4d3e2f1-0a9b-4c8d-7e6f-5a4b3c2d1e0f" }
  }
}

geofence.speeding A vehicle exceeded a geofence speed limit. Same shape as the crossing events plus the measured speed and the zone speedLimit. Fires at speeding start only.

envelope + payload

{
  "eventId": "6f708192-4354-45c6-d7e8-f9001a2b3c4d",
  "type": "geofence.speeding",
  "organisationId": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
  "occurredAt": "2026-07-09T15:03:09Z",
  "data": {
    "id": "6f708192-4354-45c6-d7e8-f9001a2b3c4d",
    "occurredAt": "2026-07-09T15:03:09Z",
    "geofence": { "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071", "name": "Trafford Park Depot" },
    "position": { "lat": 53.4662, "long": -2.3208 },
    "speed": 34,
    "speedLimit": 20,
    "device": { "hardwareId": "SMX-8841207" },
    "organisation": { "id": "b3a1e2c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d" },
    "fleet": { "id": "6d5c4b3a-2f1e-4d0c-8b7a-9e0f1a2b3c4d" },
    "vehicle": { "id": "c4d3e2f1-0a9b-4c8d-7e6f-5a4b3c2d1e0f" }
  }
}

Full webhook reference and schemas

Build fleet, video & telematics integrations on FleetLive

From zero to your first call in three steps

Get credentials

Get a token

Make your first call

~60 paths across the fleet you already run

Every event we deliver, and the exact body

Generate a client in any language