Entity Reference
Full field-level structure of every public resource — default fields, optional
fields (?fields=), expandable relationships
(?include=), filters, and one example response per
entity. 117 operations across 23 entities plus
device status, the summary aggregations, and the media, geocoding, and
text-to-speech actions. For request/response schemas,
parameters, and "Try it out", see the
API Reference.
DevicesGETPOSTPATCH
Vehicles and trackers (identity, status, group membership); live position via the status sub-resource.
devices:read devices:write Read devices and their live status
Add-on callers: Narrowed to the user's viewing groups via GroupsIds. Records with no group ids stay visible to everyone.
GETRead
List (GET /v1/devices), query (POST /v1/devices/query) and fetch one (GET /v1/devices/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
name | string | |
serial | string | Device hardware serial (ESN/IMEI). Optional, but must be unique within the company when supplied. Create-only (frozen after creation). |
type | string | Tracker type. Optional and create-only; currently only CustomTracker is accepted (any other value is rejected), and it defaults to CustomTracker when omitted. |
status | string | |
company_id | string | |
has_camera | boolean, nullable | |
last_connected_at | string (date-time) | |
last_known_location | object, nullable | Last-known GPS position from the device's latest packet. null when the device has never reported a fix. |
speed_kmh | number | |
heading | number | |
is_ignition_on | boolean | |
odometer_km | number | |
device_category | string, nullable | Normalized device category from the matching tracker type (trackertypes.DeviceCategory), e.g. "Asset Tracker". null when the device Type has no matching tracker type. |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
group_ids | array of string | |
vin | string | |
license_plate | string | |
manufacturer | string | |
model | string | |
year | number | |
engine_hours | number | |
activation_date | string (date-time) | |
tracker_model | string | |
assigned_driver_id | string | |
parent_id | string | |
asset_tag | string | |
is_active | boolean | |
one_id | string | |
region_ids | array of string | |
business_group_ids | array of string | |
altitude | number | |
state_duration_ms | number | |
last_packet_at | string (date-time) | |
last_online_packet_at | string (date-time) | |
last_gps_packet_at | string (date-time) | |
created_at | string (date-time) | |
removed_at | string (date-time) | |
shipped_at | string (date-time) | |
vendor_warranty_expires_at | string (date-time) | |
phone | string | |
geotab_serial | string | |
globalstar_esn | string | |
smartwitness_drid | string | |
billing_sku | string | |
billing_sku_id | string | |
surfsight_serial | string | |
bewhere_beacon_id | string | |
imei | string | |
comment | string | |
additional_driver_ids | array of string | |
driver_assignment_mode | string | |
custom_price | number | |
share_master_device_id | string | |
suspend_exception_video | boolean | |
is_suspended | boolean | |
camera_online | boolean | |
camera_standby | boolean | |
last_camera_contact_at | string (date-time) | |
oldest_recording_at | string (date-time) | |
latest_recording_at | string (date-time) | |
parent_geotab_id | string | |
indoor_data | object, nullable | Indoor-tracking connection data (BLE beacons only), forwarded as-is. null when not applicable. |
signal_dbm | number | |
beacon_type | string | |
is_health_recording | boolean | |
has_video_loss | boolean | |
camera_channels | array of number | |
iccid | string | |
telematic_serial | string | |
color | string | |
skill_tags | array of string | |
asset_type | string | |
image_url | string | |
asset_status | string | |
data_usage_status | string | |
termination_date | string (date-time) | |
device_plan | string | |
billing_tag | string | |
so_number | string | |
agreement_length_months | number | |
subscription_price | number | |
data_plan_mb | number | |
sim_type | string | |
is_streamax_v3 | boolean | |
has_pending_media | boolean | |
acc_status | object, nullable | Streamax ACC (ignition switch) detection state, forwarded as-is. null when not available. |
finance | object, nullable | Billing/finance details, forwarded as-is. |
config_template_id | string | |
config_template_status | string | |
config_odometer_status | string | |
last_config_template_applied_at | string (date-time) | |
last_odometer_update_at | string (date-time) | |
pending_commands | array of string | |
protocol | string | |
address | string | |
address_color | string | |
face_channel | number | |
installer_email | string | |
custom_fields | object | Tenant-defined custom field values, keyed by field name, forwarded as-is. |
device_plan_configuration | object, nullable | Device plan configuration, forwarded as-is. |
streamax_device_id | string | |
is_tracing_enabled | boolean | |
is_obd_available | boolean | |
whitelist_enabled | boolean | |
is_outdoor_ble | boolean | |
tx_power | number | |
is_obd_engine_hours_available | boolean | |
is_obd_odometer_available | boolean | |
hos_enabled | boolean | |
license_state | string | |
license_country | string | |
registration_expires_at | string (date-time) | |
switchboard_id | string |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
groups | Array of Groups | Array of Groups (empty if none) |
assigned_driver | Drivers | Drivers object (null if none) |
Filters
Filter via POST /v1/devices/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
name | eq in contains starts_with | String (case-insensitive). Discover valid values via GET /v1/devices. |
serial | eq in contains starts_with | String (case-insensitive). |
type | eq in contains starts_with | String (case-insensitive). Discover valid values via GET /v1/devices. |
status | eq in contains starts_with | String (case-insensitive). Values: Active, Suspended, Terminated. |
company_id | eq in contains starts_with | String (exact match). |
has_camera | eq | Boolean (exact match). |
last_connected_at | eq in gte lte between | Date (exact match). |
speed_kmh | eq in gte lte between | Number (exact match). |
heading | eq in gte lte between | Number (exact match). |
is_ignition_on | eq | Boolean (exact match). |
odometer_km | eq in gte lte between | Number (exact match). |
group_ids | eq in | Array of string (exact match). |
vin | eq in contains starts_with | String (case-insensitive). |
license_plate | eq in contains starts_with | String (case-insensitive). |
manufacturer | eq in contains starts_with | String (case-insensitive). |
model | eq in contains starts_with | String (case-insensitive). |
year | eq in gte lte between | Number (exact match). |
engine_hours | eq in gte lte between | Number (exact match). |
activation_date | eq in gte lte between | Date (exact match). |
tracker_model | eq in contains starts_with | String (case-insensitive). |
assigned_driver_id | eq in contains starts_with | String (exact match). |
parent_id | eq in contains starts_with | String (exact match). |
asset_tag | eq in contains starts_with | String (case-insensitive). |
is_active | eq | Boolean (exact match). |
Example
POST /v1/devices/query
{
"filters": {
"status": "Active",
"id": {
"in": [
"dvc_5f8a1c2b9e",
"dvc_9c3f21a08b"
]
},
"last_connected_at": {
"gte": "2026-07-15T08:30:00.000Z"
},
"name": {
"contains": "Truck"
}
},
"sort": "last_connected_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (type, status, name, serial, group_id, tag) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "dvc_5f8a1c2b9e",
"name": "Truck 42",
"serial": "SN-88213047",
"type": "string",
"status": "Active",
"company_id": "acme",
"has_camera": true,
"last_connected_at": "2026-07-15T08:30:00.000Z",
"last_known_location": {
"latitude": 43.6532,
"longitude": -79.3832,
"located_at": "2026-07-15T08:30:00.000Z"
},
"speed_kmh": 64.2,
"heading": 180,
"is_ignition_on": true,
"odometer_km": 104532.7,
"device_category": "string",
"group_ids": [
"grp_1a2b3c4d5e"
],
"vin": "1FTFW1E5XKF12345",
"license_plate": "ABC-1234",
"manufacturer": "Ford",
"model": "F-150",
"year": 2022,
"engine_hours": 42.5,
"activation_date": "2026-07-15T08:30:00.000Z",
"tracker_model": "GO9",
"assigned_driver_id": "drv_7a1e4c8f02",
"parent_id": "par_9c3f21a08b",
"asset_tag": "string",
"is_active": true,
"one_id": "one_9c3f21a08b",
"region_ids": [
"string"
],
"business_group_ids": [
"string"
],
"altitude": 42.5,
"state_duration_ms": 42.5,
"last_packet_at": "2026-07-15T08:30:00.000Z",
"last_online_packet_at": "2026-07-15T08:30:00.000Z",
"last_gps_packet_at": "2026-07-15T08:30:00.000Z",
"created_at": "2026-07-15T08:30:00.000Z",
"removed_at": "2026-07-15T08:30:00.000Z",
"shipped_at": "2026-07-15T08:30:00.000Z",
"vendor_warranty_expires_at": "2026-07-15T08:30:00.000Z",
"phone": "+1-555-0142",
"geotab_serial": "string",
"globalstar_esn": "string",
"smartwitness_drid": "string",
"billing_sku": "string",
"billing_sku_id": "bil_9c3f21a08b",
"surfsight_serial": "string",
"bewhere_beacon_id": "bew_9c3f21a08b",
"imei": "string",
"comment": "string",
"additional_driver_ids": [
"string"
],
"driver_assignment_mode": "string",
"custom_price": 42.5,
"share_master_device_id": "sha_9c3f21a08b",
"suspend_exception_video": true,
"is_suspended": true,
"camera_online": true,
"camera_standby": true,
"last_camera_contact_at": "2026-07-15T08:30:00.000Z",
"oldest_recording_at": "2026-07-15T08:30:00.000Z",
"latest_recording_at": "2026-07-15T08:30:00.000Z",
"parent_geotab_id": "par_9c3f21a08b",
"indoor_data": {},
"signal_dbm": 42.5,
"beacon_type": "string",
"is_health_recording": true,
"has_video_loss": true,
"camera_channels": [
42.5
],
"iccid": "string",
"telematic_serial": "string",
"color": "#2188D9",
"skill_tags": [
"hazmat"
],
"asset_type": "string",
"image_url": "string",
"asset_status": "string",
"data_usage_status": "string",
"termination_date": "2026-07-15T08:30:00.000Z",
"device_plan": "string",
"billing_tag": "string",
"so_number": "string",
"agreement_length_months": 42.5,
"subscription_price": 42.5,
"data_plan_mb": 42.5,
"sim_type": "string",
"is_streamax_v3": true,
"has_pending_media": true,
"acc_status": {},
"finance": {},
"config_template_id": "con_9c3f21a08b",
"config_template_status": "string",
"config_odometer_status": "string",
"last_config_template_applied_at": "2026-07-15T08:30:00.000Z",
"last_odometer_update_at": "2026-07-15T08:30:00.000Z",
"pending_commands": [
"string"
],
"protocol": "string",
"address": "123 Main St",
"address_color": "string",
"face_channel": 42.5,
"installer_email": "string",
"custom_fields": {},
"device_plan_configuration": {},
"streamax_device_id": "str_9c3f21a08b",
"is_tracing_enabled": true,
"is_obd_available": true,
"whitelist_enabled": true,
"is_outdoor_ble": true,
"tx_power": 42.5,
"is_obd_engine_hours_available": true,
"is_obd_odometer_available": true,
"hos_enabled": true,
"license_state": "ON",
"license_country": "CA",
"registration_expires_at": "2026-07-15T08:30:00.000Z",
"switchboard_id": "swi_9c3f21a08b",
"groups": [
{
"id": "grp_5f8a1c2b9e",
"name": "Truck 42"
}
],
"assigned_driver": {
"id": "drv_5f8a1c2b9e",
"first_name": "Jane",
"last_name": "Doe",
"username": "jdoe"
}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
POST PATCHWrite
devices:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Create — POST /v1/devices
Required: name. Full request body — every writable field (send only what you need; the required fields must be present):
{
"name": "string",
"serial": "string",
"type": "string",
"group_ids": [
"string"
],
"vin": "string",
"license_plate": "string",
"manufacturer": "string",
"model": "string",
"year": 0,
"parent_id": "string",
"asset_tag": "string",
"phone": "string",
"beacon_type": "string",
"color": "string",
"skill_tags": [
"string"
],
"asset_type": "string",
"image_url": "string",
"asset_status": "string",
"hos_enabled": true,
"license_state": "string",
"license_country": "string",
"registration_expires_at": "2026-01-01T00:00:00Z"
}
Response
{
"data": {
"id": "dvc_5f8a1c2b9e",
"name": "Truck 42",
"serial": "SN-88213047",
"type": "string",
"status": "Active",
"company_id": "acme",
"has_camera": true,
"last_connected_at": "2026-07-15T08:30:00.000Z",
"last_known_location": {
"latitude": 43.6532,
"longitude": -79.3832,
"located_at": "2026-07-15T08:30:00.000Z"
},
"speed_kmh": 64.2,
"heading": 180,
"is_ignition_on": true,
"odometer_km": 104532.7,
"device_category": "string",
"group_ids": [
"grp_1a2b3c4d5e"
],
"vin": "1FTFW1E5XKF12345",
"license_plate": "ABC-1234",
"manufacturer": "Ford",
"model": "F-150",
"year": 2022,
"engine_hours": 42.5,
"activation_date": "2026-07-15T08:30:00.000Z",
"tracker_model": "GO9",
"assigned_driver_id": "drv_7a1e4c8f02",
"parent_id": "par_9c3f21a08b",
"asset_tag": "string",
"is_active": true,
"one_id": "one_9c3f21a08b",
"region_ids": [
"string"
],
"business_group_ids": [
"string"
],
"altitude": 42.5,
"state_duration_ms": 42.5,
"last_packet_at": "2026-07-15T08:30:00.000Z",
"last_online_packet_at": "2026-07-15T08:30:00.000Z",
"last_gps_packet_at": "2026-07-15T08:30:00.000Z",
"created_at": "2026-07-15T08:30:00.000Z",
"removed_at": "2026-07-15T08:30:00.000Z",
"shipped_at": "2026-07-15T08:30:00.000Z",
"vendor_warranty_expires_at": "2026-07-15T08:30:00.000Z",
"phone": "+1-555-0142",
"geotab_serial": "string",
"globalstar_esn": "string",
"smartwitness_drid": "string",
"billing_sku": "string",
"billing_sku_id": "bil_9c3f21a08b",
"surfsight_serial": "string",
"bewhere_beacon_id": "bew_9c3f21a08b",
"imei": "string",
"comment": "string",
"additional_driver_ids": [
"string"
],
"driver_assignment_mode": "string",
"custom_price": 42.5,
"share_master_device_id": "sha_9c3f21a08b",
"suspend_exception_video": true,
"is_suspended": true,
"camera_online": true,
"camera_standby": true,
"last_camera_contact_at": "2026-07-15T08:30:00.000Z",
"oldest_recording_at": "2026-07-15T08:30:00.000Z",
"latest_recording_at": "2026-07-15T08:30:00.000Z",
"parent_geotab_id": "par_9c3f21a08b",
"indoor_data": {},
"signal_dbm": 42.5,
"beacon_type": "string",
"is_health_recording": true,
"has_video_loss": true,
"camera_channels": [
42.5
],
"iccid": "string",
"telematic_serial": "string",
"color": "#2188D9",
"skill_tags": [
"hazmat"
],
"asset_type": "string",
"image_url": "string",
"asset_status": "string",
"data_usage_status": "string",
"termination_date": "2026-07-15T08:30:00.000Z",
"device_plan": "string",
"billing_tag": "string",
"so_number": "string",
"agreement_length_months": 42.5,
"subscription_price": 42.5,
"data_plan_mb": 42.5,
"sim_type": "string",
"is_streamax_v3": true,
"has_pending_media": true,
"acc_status": {},
"finance": {},
"config_template_id": "con_9c3f21a08b",
"config_template_status": "string",
"config_odometer_status": "string",
"last_config_template_applied_at": "2026-07-15T08:30:00.000Z",
"last_odometer_update_at": "2026-07-15T08:30:00.000Z",
"pending_commands": [
"string"
],
"protocol": "string",
"address": "123 Main St",
"address_color": "string",
"face_channel": 42.5,
"installer_email": "string",
"custom_fields": {},
"device_plan_configuration": {},
"streamax_device_id": "str_9c3f21a08b",
"is_tracing_enabled": true,
"is_obd_available": true,
"whitelist_enabled": true,
"is_outdoor_ble": true,
"tx_power": 42.5,
"is_obd_engine_hours_available": true,
"is_obd_odometer_available": true,
"hos_enabled": true,
"license_state": "ON",
"license_country": "CA",
"registration_expires_at": "2026-07-15T08:30:00.000Z",
"switchboard_id": "swi_9c3f21a08b"
},
"meta": {
"request_id": "req_abc123"
}
}
Update — PATCH /v1/devices/{id}
Partial update: send only the fields you want to change (the same writable fields as create, minus create-only ones). Returns the updated record in the same envelope as above.
DriversGETPOSTPATCHDELETE
Drivers (from the users collection); credentials and security state are never exposed.
drivers:read drivers:write Read drivers
Add-on callers: Narrowed to the user's viewing groups via ViewingGroups. Records with no group ids stay visible to everyone.
GETRead
List (GET /v1/drivers), query (POST /v1/drivers/query) and fetch one (GET /v1/drivers/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
first_name | string | |
last_name | string | |
username | string | Login username. Required on create; create-only (a username change is a separate, deferred operation). A password is auto-generated when omitted. |
full_name | string, nullable |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
group_ids | array of string | Group ids the driver belongs to. Required on create — at least one group must be supplied. |
email | string | |
phone | string | |
units | string | |
language | string | |
user_type | string | |
skill_tags | array of string | |
working_hours | object | Per-day working-hours schedule, forwarded as-is (e.g. { Mon: { active, hours: { from, to } }, … }). |
created_at | string (date-time) | |
last_login | string (date-time) | |
company_id | string | |
license_number | string | |
license_state | string | |
license_country | string | |
time_zone | string | |
photo_url | string | |
telegram_chat_id | string | |
region_ids | array of string | |
business_group_ids | array of string | |
people_group_ids | array of string | |
employee_id | string | |
can_assign_job_itself | boolean | |
default_view | string | |
fetch_location_from_mobile | boolean | |
feature_preview | boolean | |
supervisor_ids | array of string | |
driver_app_data | object, nullable | Driver app data — check-in/out, breaks, work-time tracking, forwarded as-is. |
map_provider | string | |
custom_fields | object | Tenant-defined custom field values, keyed by field name, forwarded as-is. |
driver_identification | string | |
verification_phone_number | string | |
show_self_data | boolean | |
comments | string | |
live_notification_settings | object, nullable | Live-notification preferences, forwarded as-is. |
switchboard_id | string | |
hos_enabled | boolean | |
hos_exempted | boolean | |
rule_set | string | |
us_hos_cycle | string | |
home_terminal_name | string | |
home_terminal_address | object, nullable | Home-terminal location ({ Location: { latitude, longitude }, LocationName }), forwarded as-is. |
exemption_annotation | string | |
yard_move_allowed | boolean | |
personal_conveyance_allowed | boolean | |
pinned_add_in_ids | array of string | |
is_driver | boolean |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
groups | Array of Groups | Array of Groups (empty if none) |
Filters
Filter via POST /v1/drivers/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
first_name | eq in contains starts_with | String (case-insensitive). |
last_name | eq in contains starts_with | String (case-insensitive). |
username | eq in contains starts_with | String (case-insensitive). |
group_ids | eq in | Array of string (exact match). |
email | eq in contains starts_with | String (case-insensitive). |
phone | eq in contains starts_with | String (case-insensitive). |
units | eq in contains starts_with | String (case-insensitive). |
language | eq in contains starts_with | String (case-insensitive). |
user_type | eq in contains starts_with | String (case-insensitive). Values: Driver, End Customer, EndUser, General User, Passenger, Technician. |
skill_tags | eq in | Array of string (exact match). |
created_at | eq in gte lte between | Date (exact match). |
last_login | eq in gte lte between | Date (exact match). |
company_id | eq in contains starts_with | String (exact match). |
license_number | eq in contains starts_with | String (case-insensitive). |
license_state | eq in contains starts_with | String (case-insensitive). |
license_country | eq in contains starts_with | String (case-insensitive). |
Example
POST /v1/drivers/query
{
"filters": {
"user_type": "Driver",
"id": {
"in": [
"drv_5f8a1c2b9e",
"drv_9c3f21a08b"
]
},
"created_at": {
"gte": "2026-07-15T08:30:00.000Z"
},
"first_name": {
"contains": "Jane"
}
},
"sort": "created_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (username, group_id) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "drv_5f8a1c2b9e",
"first_name": "Jane",
"last_name": "Doe",
"username": "jdoe",
"full_name": "string",
"group_ids": [
"grp_1a2b3c4d5e"
],
"email": "jdoe@example.com",
"phone": "+1-555-0142",
"units": "metric",
"language": "en",
"user_type": "string",
"skill_tags": [
"hazmat"
],
"working_hours": {},
"created_at": "2026-07-15T08:30:00.000Z",
"last_login": "2026-07-15T08:30:00.000Z",
"company_id": "acme",
"license_number": "D1234-56789",
"license_state": "ON",
"license_country": "CA",
"time_zone": "string",
"photo_url": "string",
"telegram_chat_id": "tel_9c3f21a08b",
"region_ids": [
"string"
],
"business_group_ids": [
"string"
],
"people_group_ids": [
"string"
],
"employee_id": "emp_9c3f21a08b",
"can_assign_job_itself": true,
"default_view": "string",
"fetch_location_from_mobile": true,
"feature_preview": true,
"supervisor_ids": [
"string"
],
"driver_app_data": {},
"map_provider": "string",
"custom_fields": {},
"driver_identification": "string",
"verification_phone_number": "string",
"show_self_data": true,
"comments": "string",
"live_notification_settings": {},
"switchboard_id": "swi_9c3f21a08b",
"hos_enabled": true,
"hos_exempted": true,
"rule_set": "string",
"us_hos_cycle": "string",
"home_terminal_name": "string",
"home_terminal_address": {},
"exemption_annotation": "string",
"yard_move_allowed": true,
"personal_conveyance_allowed": true,
"pinned_add_in_ids": [
"string"
],
"is_driver": true,
"groups": [
{
"id": "grp_5f8a1c2b9e",
"name": "Truck 42"
}
]
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
POST PATCH DELETEWrite
drivers:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Create — POST /v1/drivers
Required: username, group_ids. Full request body — every writable field (send only what you need; the required fields must be present):
{
"first_name": "string",
"last_name": "string",
"username": "string",
"group_ids": [
"string"
],
"email": "string",
"phone": "string",
"units": "string",
"language": "string",
"user_type": "string",
"working_hours": {
"Mon": {
"active": true,
"hours": {
"from": "09:00",
"to": "17:00"
}
}
},
"license_number": "string",
"license_state": "string",
"license_country": "string",
"password": "string",
"time_zone": "string",
"photo_url": "string",
"region_ids": [
"string"
],
"business_group_ids": [
"string"
],
"people_group_ids": [
"string"
],
"employee_id": "string",
"can_assign_job_itself": true,
"default_view": "string",
"fetch_location_from_mobile": true,
"feature_preview": true,
"supervisor_ids": [
"string"
],
"driver_app_data": {},
"map_provider": "string",
"custom_fields": {},
"driver_identification": "string",
"show_self_data": true,
"comments": "string",
"live_notification_settings": {},
"hos_enabled": true,
"hos_exempted": true,
"rule_set": "string",
"us_hos_cycle": "string",
"home_terminal_name": "string",
"home_terminal_address": {
"Location": {
"latitude": 43.6532,
"longitude": -79.3832
},
"LocationName": "Main Depot"
},
"exemption_annotation": "string",
"yard_move_allowed": true,
"personal_conveyance_allowed": true,
"pinned_add_in_ids": [
"string"
]
}
Response
{
"data": {
"id": "drv_5f8a1c2b9e",
"first_name": "Jane",
"last_name": "Doe",
"username": "jdoe",
"full_name": "string",
"group_ids": [
"grp_1a2b3c4d5e"
],
"email": "jdoe@example.com",
"phone": "+1-555-0142",
"units": "metric",
"language": "en",
"user_type": "string",
"skill_tags": [
"hazmat"
],
"working_hours": {},
"created_at": "2026-07-15T08:30:00.000Z",
"last_login": "2026-07-15T08:30:00.000Z",
"company_id": "acme",
"license_number": "D1234-56789",
"license_state": "ON",
"license_country": "CA",
"time_zone": "string",
"photo_url": "string",
"telegram_chat_id": "tel_9c3f21a08b",
"region_ids": [
"string"
],
"business_group_ids": [
"string"
],
"people_group_ids": [
"string"
],
"employee_id": "emp_9c3f21a08b",
"can_assign_job_itself": true,
"default_view": "string",
"fetch_location_from_mobile": true,
"feature_preview": true,
"supervisor_ids": [
"string"
],
"driver_app_data": {},
"map_provider": "string",
"custom_fields": {},
"driver_identification": "string",
"verification_phone_number": "string",
"show_self_data": true,
"comments": "string",
"live_notification_settings": {},
"switchboard_id": "swi_9c3f21a08b",
"hos_enabled": true,
"hos_exempted": true,
"rule_set": "string",
"us_hos_cycle": "string",
"home_terminal_name": "string",
"home_terminal_address": {},
"exemption_annotation": "string",
"yard_move_allowed": true,
"personal_conveyance_allowed": true,
"pinned_add_in_ids": [
"string"
],
"is_driver": true
},
"meta": {
"request_id": "req_abc123"
}
}
Update — PATCH /v1/drivers/{id}
Partial update: send only the fields you want to change (the same writable fields as create, minus create-only ones). Returns the updated record in the same envelope as above.
Delete — DELETE /v1/drivers/{id}
Removes the record. Returns the deleted record's id.
TripsGET
Completed trips (distance, durations, speed), tenant-scoped through the owning device.
trips:read Read trips
Add-on callers: Narrowed through the owning device (DeviceId). Records whose device has no group ids stay visible to everyone.
- Supports
from/to; default last 30 days, max 31-day span.
GETRead
List (GET /v1/trips), query (POST /v1/trips/query) and fetch one (GET /v1/trips/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
device_id | string | |
driver_id | string | |
start_time | string (date-time) | |
end_time | string (date-time) | |
distance_km | number | |
idling_seconds | number, nullable | |
stop_seconds | number, nullable | |
max_speed_kmh | number | |
start_coordinates | object, nullable | GPS position. null when not resolvable. |
end_coordinates | object, nullable | GPS position. null when not resolvable. |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
start_position | string | |
end_position | string | |
bounding_box | string | |
start_address_country | string | |
start_address_state | string | |
stop_address | string | |
stop_seconds_on_start | string | |
geotab_id | string | |
ifta_report_group_id | string |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
device | Devices | Devices object (null if none) |
driver | Drivers | Drivers object (null if none) |
Filters
Filter via POST /v1/trips/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
device_id | eq in contains starts_with | String (exact match). |
driver_id | eq in contains starts_with | String (exact match). |
start_time | eq in gte lte between | Date (exact match). |
end_time | eq in gte lte between | Date (exact match). |
distance_km | eq in gte lte between | Number (exact match). |
idling_seconds | eq in gte lte between | Number (exact match). |
stop_seconds | eq in gte lte between | Number (exact match). |
max_speed_kmh | eq in gte lte between | Number (exact match). |
start_address_country | eq in contains starts_with | String (case-insensitive). |
start_address_state | eq in contains starts_with | String (case-insensitive). |
stop_address | eq in contains starts_with | String (case-insensitive). |
stop_seconds_on_start | eq in gte lte between | Number (exact match). |
Example
POST /v1/trips/query
{
"filters": {
"id": {
"in": [
"trp_5f8a1c2b9e",
"trp_9c3f21a08b"
]
},
"start_time": {
"gte": "2026-07-15T08:30:00.000Z"
},
"device_id": {
"contains": "dvc_5f8a1c2b9e"
}
},
"sort": "start_time:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (device_id, driver_id) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "trp_5f8a1c2b9e",
"device_id": "dvc_5f8a1c2b9e",
"driver_id": "drv_7a1e4c8f02",
"start_time": "2026-07-15T08:30:00.000Z",
"end_time": "2026-07-15T08:30:00.000Z",
"distance_km": 42.5,
"idling_seconds": 42.5,
"stop_seconds": 42.5,
"max_speed_kmh": 96.3,
"start_coordinates": {
"latitude": 43.6532,
"longitude": -79.3832
},
"end_coordinates": {
"latitude": 43.6532,
"longitude": -79.3832
},
"start_position": "string",
"end_position": "string",
"bounding_box": "string",
"start_address_country": "string",
"start_address_state": "string",
"stop_address": "string",
"stop_seconds_on_start": "string",
"geotab_id": "geo_9c3f21a08b",
"ifta_report_group_id": "ift_9c3f21a08b",
"device": {
"id": "dvc_5f8a1c2b9e",
"name": "Truck 42",
"serial": "SN-88213047"
},
"driver": {
"id": "drv_5f8a1c2b9e",
"first_name": "Jane",
"last_name": "Doe",
"username": "jdoe"
}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
Safety eventsGET
Rule violations / safety exceptions with derived handling status.
safety:read Read safety events
Add-on callers: Narrowed through the owning device (DeviceId). Records whose device has no group ids stay visible to everyone.
- Supports
from/to; default last 30 days, max 31-day span.
GETRead
List (GET /v1/safety-events), query (POST /v1/safety-events/query) and fetch one (GET /v1/safety-events/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
device_id | string | |
driver_id | string | |
rule_id | string | |
occurred_at | string (date-time) | |
ended_at | string (date-time) | |
speed_kmh | number | |
status | string, nullable | |
type | string, nullable | Normalized safety-event category. Derived from the raw event string (camera/AI events) or, for rule-engine events (speeding, idling, zone, fault), the linked rule's condition — so map THIS field, not rule/severity, which are null for camera events. crash is a confirmed impact; forward-collision and headway warnings are following_distance, not crash. x-extensible-enum lists the explicitly-categorised values; any other event is returned as a snake_cased form of its raw event (e.g. lens_covered) rather than a blanket other, so the set is open. |
severity | string, nullable |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
latitude | number | |
longitude | number | |
road_speed_limit_kmh | number | |
odometer_km | number | |
engine_hours | number | |
zone_id | string | |
comment | string | |
event | string | |
event_class | string | |
geotab_id | string | |
parent_device_id | string | |
username | string | |
dismiss_state | number | |
is_handled | boolean | |
notify_state | object, nullable | Deprecated notification-state payload, forwarded as-is. |
viewed | boolean | |
starred | boolean | |
engine_code | string | |
errors_description | array of string | |
indoor_position | object, nullable | Indoor position (BLE beacon events). null when not applicable. |
linked_exceptions | array of object | |
channels | string | |
job_id | string | |
stop_id | string | |
video_status | object, nullable | Status of a pending/failed video-clip request. null when no request is in flight or has ever completed. |
review_issue_id | string | |
review_issue_tag_ids | array of string | |
review_reviewer | string | |
review_date | string (date-time), nullable | |
review_coach_comment | string | |
review_coached_user_id | string | |
review_coach_date | string (date-time), nullable | |
review_coach_user_id | string | |
video | array of object | Camera clips for the event. Each element is one camera channel's recording of the event. |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
device | Devices | Devices object (null if none) |
driver | Drivers | Drivers object (null if none) |
rule | Rules | Rules object (null if none) |
zone | Zones | Zones object (null if none) |
Filters
Filter via POST /v1/safety-events/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
device_id | eq in contains starts_with | String (exact match). |
driver_id | eq in contains starts_with | String (exact match). |
rule_id | eq in contains starts_with | String (exact match). |
occurred_at | eq in gte lte between | Date (exact match). |
ended_at | eq in gte lte between | Date (exact match). |
speed_kmh | eq in gte lte between | Number (exact match). |
status | eq in | String (case-insensitive). Values: Needs Review, Needs Coaching. |
latitude | eq in gte lte between | Number (exact match). |
longitude | eq in gte lte between | Number (exact match). |
road_speed_limit_kmh | eq in gte lte between | Number (exact match). |
odometer_km | eq in gte lte between | Number (exact match). |
engine_hours | eq in gte lte between | Number (exact match). |
zone_id | eq in contains starts_with | String (exact match). |
comment | eq in contains starts_with | String (case-insensitive). |
event | eq in contains starts_with | String (case-insensitive). |
event_class | eq in contains starts_with | String (case-insensitive). |
Example
POST /v1/safety-events/query
{
"filters": {
"status": "Needs Review",
"id": {
"in": [
"evt_5f8a1c2b9e",
"evt_9c3f21a08b"
]
},
"occurred_at": {
"gte": "2026-07-15T08:30:00.000Z"
},
"device_id": {
"contains": "dvc_5f8a1c2b9e"
}
},
"sort": "occurred_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (device_id, driver_id, rule_id, zone_id, status) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "evt_5f8a1c2b9e",
"device_id": "dvc_5f8a1c2b9e",
"driver_id": "drv_7a1e4c8f02",
"rule_id": "rl_88af0c3e21",
"occurred_at": "2026-07-15T08:30:00.000Z",
"ended_at": "2026-07-15T08:30:00.000Z",
"speed_kmh": 64.2,
"status": "Active",
"type": "string",
"severity": "string",
"latitude": 43.6532,
"longitude": -79.3832,
"road_speed_limit_kmh": 100,
"odometer_km": 104532.7,
"engine_hours": 42.5,
"zone_id": "zn_3c9d2a1b55",
"comment": "string",
"event": "string",
"event_class": "string",
"geotab_id": "geo_9c3f21a08b",
"parent_device_id": "par_9c3f21a08b",
"username": "jdoe",
"dismiss_state": 42.5,
"is_handled": true,
"notify_state": {},
"viewed": true,
"starred": true,
"engine_code": "string",
"errors_description": [
"string"
],
"indoor_position": {
"x": 42.5,
"y": 42.5,
"map_id": "map_9c3f21a08b"
},
"linked_exceptions": [
{
"exception_id": "exc_9c3f21a08b",
"rule_id": "rl_88af0c3e21"
}
],
"channels": "string",
"job_id": "job_9c3f21a08b",
"stop_id": "sto_9c3f21a08b",
"video_status": {
"request_status": "string",
"error": "string",
"date": "2026-07-15T08:30:00.000Z"
},
"review_issue_id": "rev_9c3f21a08b",
"review_issue_tag_ids": [
"string"
],
"review_reviewer": "string",
"review_date": "2026-07-15T08:30:00.000Z",
"review_coach_comment": "string",
"review_coached_user_id": "rev_9c3f21a08b",
"review_coach_date": "2026-07-15T08:30:00.000Z",
"review_coach_user_id": "rev_9c3f21a08b",
"video": [
{
"channel": 3,
"facing": "forward",
"url": "https://cdn.example.com/clip.mp4",
"screenshot_url": "https://cdn.example.com/clip.jpg",
"starts_at": "2026-07-15T08:30:00.000Z",
"ends_at": "2026-07-15T08:30:00.000Z",
"ai_video_url": "https://cdn.example.com/clip-ai.mp4",
"video_id": "vid_9f31a0c2",
"mdt_url": "string",
"short_screenshot_url": "string"
}
],
"device": {
"id": "dvc_5f8a1c2b9e",
"name": "Truck 42",
"serial": "SN-88213047"
},
"driver": {
"id": "drv_5f8a1c2b9e",
"first_name": "Jane",
"last_name": "Doe",
"username": "jdoe"
},
"rule": {
"id": "rl_5f8a1c2b9e",
"name": "Truck 42",
"description": "Sample description.",
"is_active": true,
"score": 42.5,
"severity_band": "string",
"color": "#2188D9",
"rule_type": "Speed",
"trigger_type": "Threshold",
"condition_types": [
"Speed"
],
"condition": null
},
"zone": {
"id": "zn_5f8a1c2b9e",
"name": "Truck 42",
"type": "string"
}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
RulesGET
Safety rule definitions.
rules:read Read rules
Add-on callers: Narrowed to the user's viewing groups via GroupsIds. Records with no group ids stay visible to everyone.
GETRead
List (GET /v1/rules), query (POST /v1/rules/query) and fetch one (GET /v1/rules/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
name | string | |
description | string | |
is_active | boolean | |
score | number |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
group_ids | array of string | |
color | string | |
custom_message | string | |
notification_period | string | |
severity_band | string | |
rule_type | string | |
trigger_type | string | |
condition_types | array of string | Raw (non-normalized) condition leaf types found anywhere in the rule's condition tree, e.g. ["Speed"]. Includes the type from a rule's deprecated single-condition form even when condition returns only the newer tree, so an entry here may have no counterpart in condition. |
condition | RuleConditionNode | The rule's condition tree. null when the rule has no conditions. |
company_id | string | |
is_readonly | boolean | |
device_ids | array of string | |
driver_ids | array of string | |
escalations | array of object | Escalation steps (Id, Delay, DisplayDelay, DisplayDelayType, Name, UserId), forwarded as-is. |
notifications | array of object | Notification routing rules (Id, EventType, EmailTo, CustomEmails, SmsTo, CustomPhone, MessageSubject, MessageBody, TtsLanguage, TtsAudioFileId, TtsMessage, WebhookUrl, CommandChannels, CommandAction), forwarded as-is. |
notify_by_sms | boolean | |
notify_by_call | boolean | |
request_form_submission | boolean | |
form_id | string | |
attach_video | boolean | |
attach_video_enabled_at | string (date-time) | |
download_channels | array of number | |
use_snapshots | boolean | |
use_snapshots_enabled_at | string (date-time) | |
snapshot_time_length | number | |
remind | object | Maintenance-reminder detail (RemindDate, RemindMileage, Decription, DevicesIds), forwarded as-is. |
managed_review | boolean | |
coaches | array of string | |
action_data | object | Maintenance trigger/form action data, forwarded as-is. |
is_general | boolean | |
is_direct_coaching_enabled | boolean | |
notify_driver | boolean | |
rule_action | array of object | Configured rule actions (Enabled, Type, TargetGroupId), forwarded as-is. |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
groups | Array of Groups | Array of Groups (empty if none) |
Filters
Filter via POST /v1/rules/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
name | eq in contains starts_with | String (case-insensitive). Discover valid values via GET /v1/rules. |
description | eq in contains starts_with | String (case-insensitive). |
is_active | eq | Boolean (exact match). |
score | eq in gte lte between | Number (exact match). |
group_ids | eq in | Array of string (exact match). |
color | eq in contains starts_with | String (case-insensitive). |
custom_message | eq in contains starts_with | String (case-insensitive). |
notification_period | eq in contains starts_with | String (case-insensitive). |
rule_type | eq in contains starts_with | String (case-insensitive). Values: CameraSafety, CustomSafety, GeneralSafety. |
trigger_type | eq in contains starts_with | String (case-insensitive). |
Example
POST /v1/rules/query
{
"filters": {
"rule_type": "CameraSafety",
"id": {
"in": [
"rl_5f8a1c2b9e",
"rl_9c3f21a08b"
]
},
"score": {
"gte": 42.5
},
"name": {
"contains": "Truck"
}
},
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (group_id, is_active) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "rl_5f8a1c2b9e",
"name": "Truck 42",
"description": "Sample description.",
"is_active": true,
"score": 42.5,
"group_ids": [
"grp_1a2b3c4d5e"
],
"color": "#2188D9",
"custom_message": "Speeding detected",
"notification_period": "Immediate",
"severity_band": "string",
"rule_type": "Speed",
"trigger_type": "Threshold",
"condition_types": [
"Speed"
],
"condition": null,
"company_id": "acme",
"is_readonly": true,
"device_ids": [
"string"
],
"driver_ids": [
"string"
],
"escalations": [
{}
],
"notifications": [
{}
],
"notify_by_sms": true,
"notify_by_call": true,
"request_form_submission": true,
"form_id": "for_9c3f21a08b",
"attach_video": true,
"attach_video_enabled_at": "2026-07-15T08:30:00.000Z",
"download_channels": [
42.5
],
"use_snapshots": true,
"use_snapshots_enabled_at": "2026-07-15T08:30:00.000Z",
"snapshot_time_length": 42.5,
"remind": {},
"managed_review": true,
"coaches": [
"string"
],
"action_data": {},
"is_general": true,
"is_direct_coaching_enabled": true,
"notify_driver": true,
"rule_action": [
{}
],
"groups": [
{
"id": "grp_5f8a1c2b9e",
"name": "Truck 42"
}
]
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
ZonesGETPOSTPATCHDELETE
Geofences / zones.
zones:read zones:write Read zones / geofences
Add-on callers: Narrowed to the user's viewing groups via GroupIds. Records with no group ids stay visible to everyone.
GETRead
List (GET /v1/zones), query (POST /v1/zones/query) and fetch one (GET /v1/zones/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
name | string | |
type | string | The zone's tag, stored as a tag id (UUID) — not a shape or free-text category. Required on create. |
color | string | Zone display colour as a hex string, e.g. #2f80ed. Required on create. |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
group_ids | array of string | |
address | string | |
city | string | |
country | string | |
postal_code | string | |
street_address | string | |
geometry | object, nullable | Outdoor zone shape, forwarded as-is in PascalCase. Either a circle { "Type": "circle", "Center": { "Latitude": <n>, "Longitude": <n> }, "Radius": <n> } or a polygon { "Type": "polygon", "Points": [ { "Latitude": <n>, "Longitude": <n> }, … (min 3) ] }. Type must be lowercase circle or polygon. Provide EITHER geometry (outdoor, lat/lng) OR indoor_geometry + indoor_map_id (indoor) — never both. |
open_from | string | |
open_to | string | |
expected_stop_seconds | number | |
created_at | string (date-time) | |
company_id | string | |
tag_id | string | |
instructions | string | |
address_notes | string | |
state | string | |
contact_name | string | |
contact_email | string | |
phone | string | |
account_id | string | |
custom | object, nullable | Tenant-defined custom data for integrations, keyed by field name (string or number values), forwarded as-is. null when not set. |
indoor_geometry | object, nullable | Indoor zone shape on an uploaded indoor map, forwarded as-is in PascalCase (uses Center.X/Center.Y, not latitude/longitude). Requires indoor_map_id. Mutually exclusive with geometry; null for outdoor zones. |
indoor_map_id | string, nullable | Id of the indoor map an indoor zone belongs to. Required when indoor_geometry is set; must be omitted for outdoor (geometry) zones — sending it on an outdoor zone is rejected with "Outdoor zone can't have indoor map id". |
expiry | string (date-time), nullable | Zone expiration date — the collection has a TTL index that deletes expired zones. null when the zone doesn't expire. |
transparency | number | Map rendering opacity, in percent (0-100). |
unit_number | string | |
geotab_id | string |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
groups | Array of Groups | Array of Groups (empty if none) |
Filters
Filter via POST /v1/zones/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
name | eq in contains starts_with | String (case-insensitive). Discover valid values via GET /v1/zones. |
type | eq in contains starts_with | String (case-insensitive). Discover valid values via GET /v1/zones. |
color | eq in contains starts_with | String (case-insensitive). |
group_ids | eq in | Array of string (exact match). |
address | eq in contains starts_with | String (case-insensitive). |
city | eq in contains starts_with | String (case-insensitive). |
country | eq in contains starts_with | String (case-insensitive). |
postal_code | eq in contains starts_with | String (case-insensitive). |
street_address | eq in contains starts_with | String (case-insensitive). |
expected_stop_seconds | eq in gte lte between | Number (exact match). |
Example
POST /v1/zones/query
{
"filters": {
"id": {
"in": [
"zn_5f8a1c2b9e",
"zn_9c3f21a08b"
]
},
"expected_stop_seconds": {
"gte": 42.5
},
"name": {
"contains": "Truck"
}
},
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (group_id, type, name) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "zn_5f8a1c2b9e",
"name": "Truck 42",
"type": "string",
"color": "#2188D9",
"group_ids": [
"grp_1a2b3c4d5e"
],
"address": "123 Main St",
"city": "Toronto",
"country": "CA",
"postal_code": "M5V 2T6",
"street_address": "123 Main St",
"geometry": {},
"open_from": "string",
"open_to": "string",
"expected_stop_seconds": 42.5,
"created_at": "2026-07-15T08:30:00.000Z",
"company_id": "acme",
"tag_id": "tag_9c3f21a08b",
"instructions": "string",
"address_notes": "string",
"state": "string",
"contact_name": "string",
"contact_email": "string",
"phone": "+1-555-0142",
"account_id": "acc_9c3f21a08b",
"custom": {
"sample": "string"
},
"indoor_geometry": {},
"indoor_map_id": "ind_9c3f21a08b",
"expiry": "2026-07-15T08:30:00.000Z",
"transparency": 42.5,
"unit_number": "string",
"geotab_id": "geo_9c3f21a08b",
"groups": [
{
"id": "grp_5f8a1c2b9e",
"name": "Truck 42"
}
]
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
POST PATCH DELETEWrite
zones:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Create — POST /v1/zones
Required: name, type, color. Full request body — every writable field (send only what you need; the required fields must be present):
{
"name": "string",
"type": "string",
"color": "string",
"group_ids": [
"string"
],
"address": "string",
"city": "string",
"country": "string",
"postal_code": "string",
"street_address": "string",
"geometry": {
"Type": "circle",
"Center": {
"Latitude": 43.6532,
"Longitude": -79.3832
},
"Radius": 200
},
"open_from": "string",
"open_to": "string",
"expected_stop_seconds": 0,
"tag_id": "string",
"instructions": "string",
"address_notes": "string",
"state": "string",
"contact_name": "string",
"contact_email": "string",
"phone": "string",
"account_id": "string",
"custom": {},
"indoor_geometry": {
"Type": "circle",
"Center": {
"X": 120,
"Y": 240
},
"Radius": 30
},
"indoor_map_id": "string",
"expiry": "2026-01-01T00:00:00Z",
"transparency": 0,
"unit_number": "string"
}
Response
{
"data": {
"id": "zn_5f8a1c2b9e",
"name": "Truck 42",
"type": "string",
"color": "#2188D9",
"group_ids": [
"grp_1a2b3c4d5e"
],
"address": "123 Main St",
"city": "Toronto",
"country": "CA",
"postal_code": "M5V 2T6",
"street_address": "123 Main St",
"geometry": {},
"open_from": "string",
"open_to": "string",
"expected_stop_seconds": 42.5,
"created_at": "2026-07-15T08:30:00.000Z",
"company_id": "acme",
"tag_id": "tag_9c3f21a08b",
"instructions": "string",
"address_notes": "string",
"state": "string",
"contact_name": "string",
"contact_email": "string",
"phone": "+1-555-0142",
"account_id": "acc_9c3f21a08b",
"custom": {
"sample": "string"
},
"indoor_geometry": {},
"indoor_map_id": "ind_9c3f21a08b",
"expiry": "2026-07-15T08:30:00.000Z",
"transparency": 42.5,
"unit_number": "string",
"geotab_id": "geo_9c3f21a08b"
},
"meta": {
"request_id": "req_abc123"
}
}
Update — PATCH /v1/zones/{id}
Partial update: send only the fields you want to change (the same writable fields as create, minus create-only ones). Returns the updated record in the same envelope as above.
Delete — DELETE /v1/zones/{id}
Removes the record. Returns the deleted record's id.
GroupsGETPOSTPATCHDELETE
The group hierarchy used to scope and filter every other entity.
groups:read groups:write Read groups
Add-on callers: Narrowed to the groups the user themselves holds.
GETRead
List (GET /v1/groups), query (POST /v1/groups/query) and fetch one (GET /v1/groups/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
name | string | Group name. Required on create. |
child_ids | array of string, nullable |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
image_url | string | |
company_id | string | |
geotab_id | string |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/groups/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
name | eq in contains starts_with | String (case-insensitive). Discover valid values via GET /v1/groups. |
child_ids | eq in | Array of string (exact match). |
image_url | eq in contains starts_with | String (case-insensitive). |
Example
POST /v1/groups/query
{
"filters": {
"id": {
"in": [
"grp_5f8a1c2b9e",
"grp_9c3f21a08b"
]
},
"name": {
"contains": "Truck"
}
},
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (name) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "grp_5f8a1c2b9e",
"name": "Truck 42",
"child_ids": [
"grp_2b3c4d5e6f"
],
"image_url": "string",
"company_id": "acme",
"geotab_id": "geo_9c3f21a08b"
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
POST PATCH DELETEWrite
groups:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Create — POST /v1/groups
Required: name. Full request body — every writable field (send only what you need; the required fields must be present):
{
"name": "string",
"image_url": "string",
"parent_id": "string"
}
Response
{
"data": {
"id": "grp_5f8a1c2b9e",
"name": "Truck 42",
"child_ids": [
"grp_2b3c4d5e6f"
],
"image_url": "string",
"company_id": "acme",
"geotab_id": "geo_9c3f21a08b"
},
"meta": {
"request_id": "req_abc123"
}
}
Update — PATCH /v1/groups/{id}
Partial update: send only the fields you want to change (the same writable fields as create, minus create-only ones). Returns the updated record in the same envelope as above.
Delete — DELETE /v1/groups/{id}
Removes the record. Returns the deleted record's id.
Vehicle faultsGET
Detected vehicle faults with triage state, one row per fault raised on a device, scoped to the token's company. Status is one of New, Triaged, Assigned, WorkOrder, Active, Dismissed, Closed. The shared code catalog is embeddable via include=insight.
faults:read Read vehicle faults and the fault-code catalog
Add-on callers: Narrowed through the owning device (DeviceId). Records whose device has no group ids stay visible to everyone.
- Supports
from/to(optional, uncapped) — no default window; these rows are long-lived state, not events.
GETRead
List (GET /v1/faults), query (POST /v1/faults/query) and fetch one (GET /v1/faults/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
device_id | string | |
code | string | |
status | string | |
severity | string | |
title | string | |
detected_on | string (date-time) | |
created_at | string (date-time) | |
reoccurrence_count | number |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
description | string | |
category | string | |
issue_source | string | |
last_updated_at | string (date-time) | |
closed_at | string (date-time) | |
assigned_to | string | |
work_order_id | string | |
service_request_number | number | |
fault_id | string | |
timeline | array of object | Fault triage timeline entries (reported/triaged/assigned/closed/reopened/comment/linked_wo), forwarded as-is. |
attachments | array of object | Attached files ({Url, Name}), forwarded as-is. |
closed_by | string | |
watcher_ids | array of string | |
company_id | string |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
device | Devices | Devices object (null if none) |
insight | Fault codes | Fault codes object (null if none) |
Filters
Filter via POST /v1/faults/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
device_id | eq in contains starts_with | String (exact match). |
code | eq in contains starts_with | String (case-insensitive). |
status | eq in contains starts_with | String (case-insensitive). |
severity | eq in contains starts_with | String (case-insensitive). |
title | eq in contains starts_with | String (case-insensitive). |
detected_on | eq in gte lte between | Date (exact match). |
created_at | eq in gte lte between | Date (exact match). |
reoccurrence_count | eq in gte lte between | Number (exact match). |
description | eq in contains starts_with | String (case-insensitive). |
category | eq in contains starts_with | String (case-insensitive). |
issue_source | eq in contains starts_with | String (case-insensitive). |
last_updated_at | eq in gte lte between | Date (exact match). |
closed_at | eq in gte lte between | Date (exact match). |
assigned_to | eq in contains starts_with | String (case-insensitive). |
work_order_id | eq in contains starts_with | String (exact match). |
service_request_number | eq in gte lte between | Number (exact match). |
fault_id | eq in contains starts_with | String (exact match). |
Example
POST /v1/faults/query
{
"filters": {
"id": {
"in": [
"flt_5f8a1c2b9e",
"flt_9c3f21a08b"
]
},
"detected_on": {
"gte": "2026-07-15T08:30:00.000Z"
},
"device_id": {
"contains": "dvc_5f8a1c2b9e"
}
},
"sort": "created_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (device_id, code, status, severity) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "flt_5f8a1c2b9e",
"device_id": "dvc_5f8a1c2b9e",
"code": "P0171",
"status": "Active",
"severity": "string",
"title": "Check engine light",
"detected_on": "2026-07-15T08:30:00.000Z",
"created_at": "2026-07-15T08:30:00.000Z",
"reoccurrence_count": 42.5,
"description": "Sample description.",
"category": "Engine",
"issue_source": "OBD",
"last_updated_at": "2026-07-15T08:30:00.000Z",
"closed_at": "2026-07-15T08:30:00.000Z",
"assigned_to": "Jane Doe",
"work_order_id": "wo_20394",
"service_request_number": 42.5,
"fault_id": "flt_4b6e9a0d77",
"timeline": [
{}
],
"attachments": [
{}
],
"closed_by": "string",
"watcher_ids": [
"string"
],
"company_id": "acme",
"device": {
"id": "dvc_5f8a1c2b9e",
"name": "Truck 42",
"serial": "SN-88213047"
},
"insight": {
"code": "P0171",
"component": "Fuel System",
"severity": "string",
"summary": "System running too lean.",
"description": "Sample description.",
"source": "OEM",
"detected_symptoms": [
"Check engine light on"
],
"recommended_actions": [
"Inspect wiring harness"
],
"most_likely_root_cause": {
"cause": "Loose gas cap",
"confidence_level": 82
},
"potential_impact": [
"Reduced fuel efficiency"
],
"manufacturer": "Ford",
"model": "F-150",
"make_year": "string"
}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
Fault codesGET
Global, AI-enriched diagnostic-code catalog (shared reference data; no tenant scoping).
faults:read Read vehicle faults and the fault-code catalog
Add-on callers: Not group-scoped — Cross-tenant fault-code catalog (global: true).
GETRead
List (GET /v1/fault-codes), query (POST /v1/fault-codes/query) and fetch one (GET /v1/fault-codes/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
code | string | |
component | string | |
severity | string | |
summary | string | |
source | string |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
description | string | |
detected_symptoms | array of string | |
recommended_actions | array of string | |
most_likely_root_cause | object, nullable | AI-assessed most likely root cause. null when the catalog row has no assessment. |
potential_impact | array of string | |
manufacturer | string | |
model | string | |
protocol | string | |
make_year | string |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/fault-codes/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
code | eq in contains starts_with | String (case-insensitive). |
component | eq in contains starts_with | String (case-insensitive). |
severity | eq in contains starts_with | String (case-insensitive). Values: Low, Moderate, High, Critical. |
summary | eq in contains starts_with | String (case-insensitive). |
source | eq in contains starts_with | String (case-insensitive). |
description | eq in contains starts_with | String (case-insensitive). |
detected_symptoms | eq in | Array of string (exact match). |
recommended_actions | eq in | Array of string (exact match). |
potential_impact | eq in | Array of string (exact match). |
manufacturer | eq in contains starts_with | String (case-insensitive). |
model | eq in contains starts_with | String (case-insensitive). |
protocol | eq in contains starts_with | String (case-insensitive). |
make_year | eq in gte lte between | String (case-insensitive). |
Example
POST /v1/fault-codes/query
{
"filters": {
"severity": "Low",
"id": {
"in": [
"fc_5f8a1c2b9e",
"fc_9c3f21a08b"
]
},
"make_year": {
"gte": "Make year"
},
"code": {
"contains": "P0171"
}
},
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (code, component, severity) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "fc_5f8a1c2b9e",
"code": "P0171",
"component": "Fuel System",
"severity": "string",
"summary": "System running too lean.",
"source": "OEM",
"description": "Sample description.",
"detected_symptoms": [
"Check engine light on"
],
"recommended_actions": [
"Inspect wiring harness"
],
"most_likely_root_cause": {
"cause": "Loose gas cap",
"confidence_level": 82
},
"potential_impact": [
"Reduced fuel efficiency"
],
"manufacturer": "Ford",
"model": "F-150",
"protocol": "string",
"make_year": "string"
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
Maintenance requestsGETPOSTPATCHDELETE
Vehicle maintenance service requests.
maintenance:read maintenance:write Read maintenance requests and repair orders
Add-on callers: Narrowed through the owning device (details.asset). Records whose device has no group ids stay visible to everyone.
- Supports
from/to; default last 30 days, max 31-day span.
GETRead
List (GET /v1/maintenance-requests), query (POST /v1/maintenance-requests/query) and fetch one (GET /v1/maintenance-requests/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
service_number | number | |
status | string | |
odometer_km | number | |
engine_hours | number | |
created_at | string (date-time) | |
resolved_at | string (date-time) | |
total_cost | number |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
details | object | Maintenance request details, forwarded as-is (camelCase sub-keys) to the maintenance service. Required on create — the request is built from this object. In practice set asset (the vehicle/device id) and a valid dueDate; the other sub-keys are optional. |
labour_cost | number | |
parts_cost | number | |
service_cost | number | |
tags | array of string | |
created_by | string | |
resolved_by | string | |
is_open | boolean | |
company_id | string | |
status_changed_at | string (date-time) | |
source | string | |
repair_order_number | number | |
repair_order_id | string | |
service_provider_id | string | |
logged_time | number | |
added_to_repair | boolean | |
assigned_to | string | |
assigned_by | string | |
assigned_at | string (date-time) | |
resolved_odometer_km | number | |
resolved_engine_hours | number | |
rule_id | string | |
cancellation_reason | string | |
completion_odometer_km | number | |
completion_engine_hours | number | |
completed_at | string (date-time) | |
added_products | array of object | Product/part line items attached to the request, forwarded as-is (camelCase sub-keys, matching the stored shape). |
product_labours | string | |
defect | string | |
submission_ids | array of string |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/maintenance-requests/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
service_number | eq in gte lte between | Number (exact match). |
status | eq in contains starts_with | String (case-insensitive). Values: Pending Assignment, Assigned, In Progress, On Hold, Completed, Cancelled. |
odometer_km | eq in gte lte between | Number (exact match). |
engine_hours | eq in gte lte between | Number (exact match). |
created_at | eq in gte lte between | Date (exact match). |
resolved_at | eq in gte lte between | Date (exact match). |
total_cost | eq in gte lte between | Number (exact match). |
labour_cost | eq in gte lte between | Number (exact match). |
parts_cost | eq in gte lte between | Number (exact match). |
service_cost | eq in gte lte between | Number (exact match). |
tags | eq in | Array of string (exact match). |
created_by | eq in contains starts_with | String (case-insensitive). |
resolved_by | eq in contains starts_with | String (case-insensitive). |
is_open | eq | Boolean (exact match). |
Example
POST /v1/maintenance-requests/query
{
"filters": {
"status": "Pending Assignment",
"id": {
"in": [
"mr_5f8a1c2b9e",
"mr_9c3f21a08b"
]
},
"service_number": {
"gte": 42.5
},
"created_by": {
"contains": "jdoe"
}
},
"sort": "created_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (status) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "mr_5f8a1c2b9e",
"service_number": 42.5,
"status": "Active",
"odometer_km": 104532.7,
"engine_hours": 42.5,
"created_at": "2026-07-15T08:30:00.000Z",
"resolved_at": "2026-07-15T08:30:00.000Z",
"total_cost": 42.5,
"details": {
"asset": "string",
"maintenanceType": "string",
"reference": "string",
"dueDate": "2026-07-15T08:30:00.000Z",
"summary": "System running too lean.",
"priority": "string"
},
"labour_cost": 42.5,
"parts_cost": 42.5,
"service_cost": 42.5,
"tags": [
"priority"
],
"created_by": "jdoe",
"resolved_by": "jdoe",
"is_open": true,
"company_id": "acme",
"status_changed_at": "2026-07-15T08:30:00.000Z",
"source": "OEM",
"repair_order_number": 42.5,
"repair_order_id": "rep_9c3f21a08b",
"service_provider_id": "ser_9c3f21a08b",
"logged_time": 42.5,
"added_to_repair": true,
"assigned_to": "Jane Doe",
"assigned_by": "string",
"assigned_at": "2026-07-15T08:30:00.000Z",
"resolved_odometer_km": 42.5,
"resolved_engine_hours": 42.5,
"rule_id": "rl_88af0c3e21",
"cancellation_reason": "string",
"completion_odometer_km": 42.5,
"completion_engine_hours": 42.5,
"completed_at": "2026-07-15T08:30:00.000Z",
"added_products": [
{
"id": "mr_5f8a1c2b9e",
"name": "Truck 42",
"type": "string",
"quantityOrHours": 42.5,
"unitCost": 42.5,
"totalCost": 42.5,
"disableUnitCost": true,
"estimatedTime": 42.5
}
],
"product_labours": "string",
"defect": "string",
"submission_ids": [
"string"
]
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
POST PATCH DELETEWrite
maintenance:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Create — POST /v1/maintenance-requests
Required: details. Full request body — every writable field (send only what you need; the required fields must be present):
{
"status": "string",
"details": {
"asset": "string",
"maintenanceType": "string",
"reference": "string",
"dueDate": "2026-01-01T00:00:00Z",
"summary": "string",
"priority": "string"
},
"tags": [
"string"
],
"service_provider_id": "string",
"assigned_to": "string",
"added_products": [
{
"id": "string",
"name": "string",
"type": "string",
"quantityOrHours": 0,
"unitCost": 0,
"totalCost": 0,
"disableUnitCost": true,
"estimatedTime": 0
}
],
"defect": "string"
}
Response
{
"data": {
"id": "mr_5f8a1c2b9e",
"service_number": 42.5,
"status": "Active",
"odometer_km": 104532.7,
"engine_hours": 42.5,
"created_at": "2026-07-15T08:30:00.000Z",
"resolved_at": "2026-07-15T08:30:00.000Z",
"total_cost": 42.5,
"details": {
"asset": "string",
"maintenanceType": "string",
"reference": "string",
"dueDate": "2026-07-15T08:30:00.000Z",
"summary": "System running too lean.",
"priority": "string"
},
"labour_cost": 42.5,
"parts_cost": 42.5,
"service_cost": 42.5,
"tags": [
"priority"
],
"created_by": "jdoe",
"resolved_by": "jdoe",
"is_open": true,
"company_id": "acme",
"status_changed_at": "2026-07-15T08:30:00.000Z",
"source": "OEM",
"repair_order_number": 42.5,
"repair_order_id": "rep_9c3f21a08b",
"service_provider_id": "ser_9c3f21a08b",
"logged_time": 42.5,
"added_to_repair": true,
"assigned_to": "Jane Doe",
"assigned_by": "string",
"assigned_at": "2026-07-15T08:30:00.000Z",
"resolved_odometer_km": 42.5,
"resolved_engine_hours": 42.5,
"rule_id": "rl_88af0c3e21",
"cancellation_reason": "string",
"completion_odometer_km": 42.5,
"completion_engine_hours": 42.5,
"completed_at": "2026-07-15T08:30:00.000Z",
"added_products": [
{
"id": "mr_5f8a1c2b9e",
"name": "Truck 42",
"type": "string",
"quantityOrHours": 42.5,
"unitCost": 42.5,
"totalCost": 42.5,
"disableUnitCost": true,
"estimatedTime": 42.5
}
],
"product_labours": "string",
"defect": "string",
"submission_ids": [
"string"
]
},
"meta": {
"request_id": "req_abc123"
}
}
Update — PATCH /v1/maintenance-requests/{id}
Partial update: send only the fields you want to change (the same writable fields as create, minus create-only ones). Returns the updated record in the same envelope as above.
Delete — DELETE /v1/maintenance-requests/{id}
Removes the record. Returns the deleted record's id.
Repair ordersGETPOSTPATCHDELETE
Repair orders (curated totals; raw cost breakdowns hidden).
maintenance:read maintenance:write Read maintenance requests and repair orders
Add-on callers: Narrowed through the owning device (details.asset). Records whose device has no group ids stay visible to everyone.
- Supports
from/to; default last 30 days, max 31-day span.
GETRead
List (GET /v1/repair-orders), query (POST /v1/repair-orders/query) and fetch one (GET /v1/repair-orders/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
order_number | number | |
status | string | |
total_cost | number, nullable | |
created_at | string (date-time) | |
request_count | number, nullable | |
service_request_ids | array of string |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
details | object | Repair order details, forwarded as-is (camelCase sub-keys) to the maintenance service. Required on create; in practice set asset and a valid dueDate. assignTo/serviceProvider also propagate onto the linked service requests. |
assigned_at | string (date-time) | |
assigned_by | string | |
added_services | array of string | Maintenance service request ids attached to this repair order. Required on create: at least one id, each an existing service request in the company that is not already attached to another repair order. |
company_id | string | |
created_by | string | |
resolved_by | string | |
resolved_at | string (date-time) | |
status_changed_at | string (date-time) | |
cancellation_reason | string | |
product_labours | array of object | |
estimated_time | number | |
logged_time | number | |
service_amount | number | |
goods_amount | number | |
subtotal | number | |
discount | object, nullable | Discount applied to the order total. null when summary/discount isn't set. |
tax | object, nullable | Tax applied to the order total. null when summary/tax isn't set. |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/repair-orders/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
order_number | eq in gte lte between | Number (exact match). |
status | eq in contains starts_with | String (case-insensitive). Values: Pending Assignment, Assigned, In Progress, On Hold, Completed, Cancelled. |
created_at | eq in gte lte between | Date (exact match). |
service_request_ids | eq in | Array of string (exact match). |
assigned_at | eq in gte lte between | Date (exact match). |
assigned_by | eq in contains starts_with | String (case-insensitive). |
added_services | eq in | Array of string (exact match). |
Example
POST /v1/repair-orders/query
{
"filters": {
"status": "Pending Assignment",
"id": {
"in": [
"ro_5f8a1c2b9e",
"ro_9c3f21a08b"
]
},
"order_number": {
"gte": 42.5
},
"assigned_by": {
"contains": "Assigned"
}
},
"sort": "created_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (status) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "ro_5f8a1c2b9e",
"order_number": 42.5,
"status": "Active",
"total_cost": 42.5,
"created_at": "2026-07-15T08:30:00.000Z",
"request_count": 42.5,
"service_request_ids": [
"sr_10293"
],
"details": {
"asset": "string",
"priority": "string",
"assignTo": "string",
"serviceProvider": "string",
"summary": "System running too lean.",
"dueDate": "2026-07-15T08:30:00.000Z",
"reference": "string"
},
"assigned_at": "2026-07-15T08:30:00.000Z",
"assigned_by": "string",
"added_services": [
"string"
],
"company_id": "acme",
"created_by": "jdoe",
"resolved_by": "jdoe",
"resolved_at": "2026-07-15T08:30:00.000Z",
"status_changed_at": "2026-07-15T08:30:00.000Z",
"cancellation_reason": "string",
"product_labours": [
{
"id": "ro_5f8a1c2b9e",
"name": "Truck 42"
}
],
"estimated_time": 42.5,
"logged_time": 42.5,
"service_amount": 42.5,
"goods_amount": 42.5,
"subtotal": 42.5,
"discount": {
"value": 42.5,
"type": "Dollar",
"final_value": 42.5
},
"tax": {
"value": 42.5,
"type": "Dollar",
"final_value": 42.5
}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
POST PATCH DELETEWrite
maintenance:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Create — POST /v1/repair-orders
Required: details, added_services. Full request body — every writable field (send only what you need; the required fields must be present):
{
"status": "string",
"details": {
"asset": "string",
"priority": "string",
"assignTo": "string",
"serviceProvider": "string",
"summary": "string",
"dueDate": "2026-01-01T00:00:00Z",
"reference": "string"
},
"added_services": [
"string"
]
}
Response
{
"data": {
"id": "ro_5f8a1c2b9e",
"order_number": 42.5,
"status": "Active",
"total_cost": 42.5,
"created_at": "2026-07-15T08:30:00.000Z",
"request_count": 42.5,
"service_request_ids": [
"sr_10293"
],
"details": {
"asset": "string",
"priority": "string",
"assignTo": "string",
"serviceProvider": "string",
"summary": "System running too lean.",
"dueDate": "2026-07-15T08:30:00.000Z",
"reference": "string"
},
"assigned_at": "2026-07-15T08:30:00.000Z",
"assigned_by": "string",
"added_services": [
"string"
],
"company_id": "acme",
"created_by": "jdoe",
"resolved_by": "jdoe",
"resolved_at": "2026-07-15T08:30:00.000Z",
"status_changed_at": "2026-07-15T08:30:00.000Z",
"cancellation_reason": "string",
"product_labours": [
{
"id": "ro_5f8a1c2b9e",
"name": "Truck 42"
}
],
"estimated_time": 42.5,
"logged_time": 42.5,
"service_amount": 42.5,
"goods_amount": 42.5,
"subtotal": 42.5,
"discount": {
"value": 42.5,
"type": "Dollar",
"final_value": 42.5
},
"tax": {
"value": 42.5,
"type": "Dollar",
"final_value": 42.5
}
},
"meta": {
"request_id": "req_abc123"
}
}
Update — PATCH /v1/repair-orders/{id}
Partial update: send only the fields you want to change (the same writable fields as create, minus create-only ones). Returns the updated record in the same envelope as above.
Delete — DELETE /v1/repair-orders/{id}
Removes the record. Returns the deleted record's id.
Diagnostic readingsGET
Sensor/telemetry time-series (list-only, date-cursored).
diagnostics:read Read diagnostic readings
Add-on callers: Narrowed through the owning device (DeviceId). Records whose device has no group ids stay visible to everyone.
- Supports
from/to; default last 30 days, max 31-day span. - Required filter(s):
device_id. - List-only — no
GET /diagnostics/{id}route.
GETRead
List (GET /v1/diagnostics), query (POST /v1/diagnostics/query) and fetch one (GET /v1/diagnostics/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
device_id | string | |
type | string | |
value | number | |
recorded_at | string (date-time) |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
text_value | string | |
diff | string | |
source | string |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
device | Devices | Devices object (null if none) |
Filters
Filter via POST /v1/diagnostics/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
device_id | eq in contains starts_with | String (exact match). Required. |
type | eq in contains starts_with | String (case-insensitive). Values: InDoor, OutDoor, DoorState, RemovalState, BLEConnection, Battery, Humidity, Temperature, Impact, Pressure, Light, Tamper, RSSI, Fuel, FuelLevel, Odometer, TirePressureLF, TirePressureRF, TirePressureLR, TirePressureRR, CoolantTemperature, BatteryVoltage, BackupBatteryVoltage, EngineOnTime, RPM, EngineSpeed, EngineHours, EngineLoad, TotalMileage, AverageOilConsumption, Break, OilPressure, MassAirFlow, Ignition, AccAxisX, AccAxisY, AccAxisZ, Button, Fault, RemainingFuel, InstantFuelConsumption, TotalFuel, MovingMode, Interrupt, Speed, EngineTemperature, FuelRate, BatteryTemperature, OBDIgnition, LoadPercentage, LoadingMode, FloorCapacityRatio, FloorAreaRemaining, PowerSource, ChargeType. |
value | eq in gte lte between | Number (exact match). |
recorded_at | eq in gte lte between | Date (exact match). |
text_value | eq in contains starts_with | String (case-insensitive). |
diff | eq in gte lte between | Number (exact match). |
source | eq in contains starts_with | String (case-insensitive). |
Example
POST /v1/diagnostics/query
{
"filters": {
"type": "InDoor",
"device_id": {
"in": [
"dvc_5f8a1c2b9e",
"dvc_9c3f21a08b"
]
},
"value": {
"gte": 42.5
},
"source": {
"contains": "OEM"
}
},
"sort": "recorded_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (device_id, type) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"device_id": "dvc_5f8a1c2b9e",
"type": "string",
"value": 42.5,
"recorded_at": "2026-07-15T08:30:00.000Z",
"text_value": "string",
"diff": "string",
"source": "OEM",
"device": {
"id": "dvc_5f8a1c2b9e",
"name": "Truck 42",
"serial": "SN-88213047"
}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
LocationsGET
Historical vehicle locations / breadcrumbs (list-only, date-cursored).
locations:read Read historical vehicle locations
Add-on callers: Narrowed through the owning device (DeviceId). Records whose device has no group ids stay visible to everyone.
- Supports
from/to; default last 30 days, max 31-day span. - Required filter(s):
device_id. - List-only — no
GET /locations/{id}route.
GETRead
List (GET /v1/locations), query (POST /v1/locations/query) and fetch one (GET /v1/locations/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
device_id | string | |
located_at | string (date-time) | |
timezone | string, nullable | |
latitude | number | |
longitude | number | |
speed_kmh | number | |
heading | number |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
altitude | string | |
hdop | number, nullable | Horizontal dilution of precision of the GPS fix. Lower is more precise. null when the device didn't report it. |
satellite_count | integer, nullable | Number of satellites used for the GPS fix. null when the device didn't report it. |
road_speed_limit_kmh | number | |
event | string | |
odometer_km | number | |
battery_percentage | string | |
battery_voltage | string | |
external_adc_voltage | string | |
rfid_scan | string | |
alarm_input | string | |
engine_code | string | |
errors_description | array of string | |
source_type | string | |
indoor_position | object, nullable | Position on the indoor map ({x, y, map_id}), forwarded from the stored Indoor sub-document. null when not applicable. |
passenger_count | number | |
channels | string | |
event_action | string |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
device | Devices | Devices object (null if none) |
Filters
Filter via POST /v1/locations/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
device_id | eq in contains starts_with | String (exact match). Required. |
located_at | eq in gte lte between | Date (exact match). |
latitude | eq in gte lte between | Number (exact match). |
longitude | eq in gte lte between | Number (exact match). |
speed_kmh | eq in gte lte between | Number (exact match). |
heading | eq in gte lte between | Number (exact match). |
altitude | eq in gte lte between | Number (exact match). |
hdop | eq in gte lte between | Number (exact match). |
satellite_count | eq in gte lte between | Number (exact match). |
road_speed_limit_kmh | eq in gte lte between | Number (exact match). |
event | eq in contains starts_with | String (case-insensitive). |
battery_percentage | eq in gte lte between | Number (exact match). |
battery_voltage | eq in gte lte between | Number (exact match). |
external_adc_voltage | eq in gte lte between | Number (exact match). |
rfid_scan | eq in contains starts_with | String (case-insensitive). |
alarm_input | eq in contains starts_with | String (case-insensitive). |
engine_code | eq in contains starts_with | String (case-insensitive). |
source_type | eq in gte lte between | Number (exact match). |
passenger_count | eq in gte lte between | Number (exact match). |
channels | eq in contains starts_with | String (case-insensitive). |
event_action | eq in contains starts_with | String (case-insensitive). |
Example
POST /v1/locations/query
{
"filters": {
"device_id": {
"in": [
"dvc_5f8a1c2b9e",
"dvc_9c3f21a08b"
]
},
"located_at": {
"gte": "2026-07-15T08:30:00.000Z"
},
"event": {
"contains": "Event"
}
},
"sort": "located_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (device_id) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"device_id": "dvc_5f8a1c2b9e",
"located_at": "2026-07-15T08:30:00.000Z",
"timezone": "string",
"latitude": 43.6532,
"longitude": -79.3832,
"speed_kmh": 64.2,
"heading": 180,
"altitude": "string",
"hdop": 42.5,
"satellite_count": 3,
"road_speed_limit_kmh": 100,
"event": "string",
"odometer_km": 104532.7,
"battery_percentage": "string",
"battery_voltage": "string",
"external_adc_voltage": "string",
"rfid_scan": "string",
"alarm_input": "string",
"engine_code": "string",
"errors_description": [
"string"
],
"source_type": "string",
"indoor_position": {},
"passenger_count": 42.5,
"channels": "string",
"event_action": "string",
"device": {
"id": "dvc_5f8a1c2b9e",
"name": "Truck 42",
"serial": "SN-88213047"
}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
FormsGETDELETE
Company form definitions (layout, DVIR/safety config, reusability); notification routing details are never exposed.
forms:read forms:write Read forms, submissions and schedules
Add-on callers: Narrowed to the user's viewing groups via groupsIds. Records with no group ids stay visible to everyone.
GETRead
List (GET /v1/forms), query (POST /v1/forms/query) and fetch one (GET /v1/forms/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
name | string | |
description | string | |
form_category | string | |
status | string | |
created | string | |
created_by | string | |
estimate_time_in_minutes | string | |
is_reusable | boolean | |
group_ids | array of string | |
device_ids | array of string | |
driver_ids | array of string | |
tags | array of string |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
layout | string | |
mobile_layout | string | |
dvir_config | string | |
safety_config | string | |
custom_field_config | string | |
company_id | string | |
tag_id | string | |
form_condition_groups | array of object | Show/hide conditional-logic groups keyed by fieldId, forwarded as-is. |
form_notification | array of object | Submit-notification routing (EventType, CustomEmails, CustomPhone), forwarded as-is. |
is_send_notification | boolean | |
send_for_approval | boolean |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/forms/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
No field filters. Use the list controls below.
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (form_category, status, driver_id, group_id, device_id) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "id_5f8a1c2b9e",
"name": "Truck 42",
"description": "Sample description.",
"form_category": "string",
"status": "Active",
"created": "string",
"created_by": "jdoe",
"estimate_time_in_minutes": "string",
"is_reusable": true,
"group_ids": [
"grp_1a2b3c4d5e"
],
"device_ids": [
"string"
],
"driver_ids": [
"string"
],
"tags": [
"priority"
],
"layout": "string",
"mobile_layout": "string",
"dvir_config": "string",
"safety_config": "string",
"custom_field_config": "string",
"company_id": "acme",
"tag_id": "tag_9c3f21a08b",
"form_condition_groups": [
{}
],
"form_notification": [
{}
],
"is_send_notification": true,
"send_for_approval": true
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
DELETEWrite
forms:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Delete — DELETE /v1/forms/{id}
Removes the record. Returns the deleted record's id.
Form submissionsGET
Submitted forms (dispatch tasks carrying a completed form), list-only and date-cursored; raw layout is sanitized into answers.
forms:read Read forms, submissions and schedules
Add-on callers: Narrowed to the user's viewing groups via groupsIds. Records with no group ids stay visible to everyone.
- Supports
from/to; default last 30 days, max 31-day span. - List-only — no
GET /form-submissions/{id}route.
GETRead
List (GET /v1/form-submissions), query (POST /v1/form-submissions/query) and fetch one (GET /v1/form-submissions/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
form_id | string | |
name | string | |
form_category | string | |
assigned_driver_id | string | |
status | string | |
created | string | |
created_by | string | |
submitted | string | |
submitted_by | string | |
device_id | string | |
submitted_location | string, nullable | |
job | string | |
note | string | |
form_description | string |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
answers | array of object | |
dispatch_location | string | |
updated | string | |
updated_by | string | |
rejected | string | |
rejected_by | string | |
rejected_note | string | |
approved_on | string | |
approved_by | string | |
needs_supervisor_approval | string | |
dvir_config | string | |
company_id | string | |
group_ids | array of string | |
device_ids | array of string | |
driver_ids | array of string | |
tags | array of string | |
tag_id | string | |
mobile_layout | string | |
estimate_time_in_minutes | number, nullable |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/form-submissions/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
No field filters. Use the list controls below.
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (driver_id, status, form_id, device_id, form_category) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "id_5f8a1c2b9e",
"form_id": "for_9c3f21a08b",
"name": "Truck 42",
"form_category": "string",
"assigned_driver_id": "drv_7a1e4c8f02",
"status": "Active",
"created": "string",
"created_by": "jdoe",
"submitted": "string",
"submitted_by": "string",
"device_id": "dvc_5f8a1c2b9e",
"submitted_location": "string",
"job": "string",
"note": "string",
"form_description": "string",
"answers": [
{
"label": "string",
"name": "Truck 42",
"value": {},
"type": "string",
"options": [
{}
],
"files": [
"string"
],
"location": {
"lat": 42.5,
"lng": 42.5
},
"unit_field_detail": {
"unit": "string",
"value": {}
}
}
],
"dispatch_location": "string",
"updated": "string",
"updated_by": "string",
"rejected": "string",
"rejected_by": "string",
"rejected_note": "string",
"approved_on": "string",
"approved_by": "string",
"needs_supervisor_approval": "string",
"dvir_config": "string",
"company_id": "acme",
"group_ids": [
"grp_1a2b3c4d5e"
],
"device_ids": [
"string"
],
"driver_ids": [
"string"
],
"tags": [
"priority"
],
"tag_id": "tag_9c3f21a08b",
"mobile_layout": "string",
"estimate_time_in_minutes": 42.5
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
Form schedulesGET
Scheduled form dispatches — one row per scheduled execution of a form on a device/driver.
forms:read Read forms, submissions and schedules
Add-on callers: Not group-scoped — No group field on ScheduledFormDispatches.
- Supports
from/to(optional, uncapped) — no default window; these rows are long-lived state, not events.
GETRead
List (GET /v1/form-schedules), query (POST /v1/form-schedules/query) and fetch one (GET /v1/form-schedules/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
status | string | |
recurrence | string | |
next_run_at | string (date-time) | |
last_run_at | string (date-time) | |
created_by | string | |
created_at | string (date-time) | |
updated_at | string (date-time) | |
last_dispatch_task_ids | array of string |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
None.
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/form-schedules/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
No field filters. Use the list controls below.
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (status) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "id_5f8a1c2b9e",
"status": "Active",
"recurrence": "string",
"next_run_at": "2026-07-15T08:30:00.000Z",
"last_run_at": "2026-07-15T08:30:00.000Z",
"created_by": "jdoe",
"created_at": "2026-07-15T08:30:00.000Z",
"updated_at": "2026-07-15T08:30:00.000Z",
"last_dispatch_task_ids": [
"string"
]
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
ProductsGETPOSTPATCHDELETE
Marketplace/dispatch products (pricing, stock, zone/device association).
products:read products:write Read products
Add-on callers: Not group-scoped — Parts catalog; no group dimension.
GETRead
List (GET /v1/products), query (POST /v1/products/query) and fetch one (GET /v1/products/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
name | string | |
description | string | |
price | number | |
unique_id | string | |
title | string |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
image_url | string | |
zone_id | string | |
type | string | |
quantity_in_hand | number | |
tags | array of string | |
device_ids | array of string | |
is_archived | boolean | |
is_marketplace_product | boolean | |
created_at | string (date-time) | |
company_id | string | |
order_lead_time | object, nullable | Order lead time before dispatch ({ Days, Hours, Minutes }), forwarded as-is. |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/products/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
name | eq in contains starts_with | String (case-insensitive). Discover valid values via GET /v1/products. |
price | eq in gte lte between | Number (exact match). |
unique_id | eq in contains starts_with | String (exact match). |
zone_id | eq in contains starts_with | String (exact match). |
quantity_in_hand | eq in gte lte between | Number (exact match). |
tags | eq in | Array of string (exact match). |
device_ids | eq in | Array of string (exact match). |
is_archived | eq | Boolean (exact match). |
is_marketplace_product | eq | Boolean (exact match). |
created_at | eq in gte lte between | Date (exact match). |
company_id | eq in contains starts_with | String (exact match). |
Example
POST /v1/products/query
{
"filters": {
"id": {
"in": [
"id_5f8a1c2b9e",
"id_9c3f21a08b"
]
},
"price": {
"gte": 42.5
},
"name": {
"contains": "Truck"
}
},
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (name, zone_id) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "id_5f8a1c2b9e",
"name": "Truck 42",
"description": "Sample description.",
"price": 42.5,
"unique_id": "uni_9c3f21a08b",
"title": "Check engine light",
"image_url": "string",
"zone_id": "zn_3c9d2a1b55",
"type": "string",
"quantity_in_hand": 42.5,
"tags": [
"priority"
],
"device_ids": [
"string"
],
"is_archived": true,
"is_marketplace_product": true,
"created_at": "2026-07-15T08:30:00.000Z",
"company_id": "acme",
"order_lead_time": {}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
POST PATCH DELETEWrite
products:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Create — POST /v1/products
Required: none — send at least one writable field. Full request body — every writable field (send only what you need; the required fields must be present):
{
"name": "string",
"description": "string",
"price": 0,
"unique_id": "string",
"title": "string",
"image_url": "string",
"zone_id": "string",
"type": "string",
"quantity_in_hand": 0,
"tags": [
"string"
],
"device_ids": [
"string"
],
"is_archived": true,
"is_marketplace_product": true,
"order_lead_time": {
"Days": 1,
"Hours": 2,
"Minutes": 0
}
}
Response
{
"data": {
"id": "id_5f8a1c2b9e",
"name": "Truck 42",
"description": "Sample description.",
"price": 42.5,
"unique_id": "uni_9c3f21a08b",
"title": "Check engine light",
"image_url": "string",
"zone_id": "zn_3c9d2a1b55",
"type": "string",
"quantity_in_hand": 42.5,
"tags": [
"priority"
],
"device_ids": [
"string"
],
"is_archived": true,
"is_marketplace_product": true,
"created_at": "2026-07-15T08:30:00.000Z",
"company_id": "acme",
"order_lead_time": {}
},
"meta": {
"request_id": "req_abc123"
}
}
Update — PATCH /v1/products/{id}
Partial update: send only the fields you want to change (the same writable fields as create, minus create-only ones). Returns the updated record in the same envelope as above.
Delete — DELETE /v1/products/{id}
Removes the record. Returns the deleted record's id.
JobsGETPOSTPATCHDELETE
Dispatch jobs (work orders) with stops, assignment and status. Update is metadata-only — stops/device/user/assignment-type are create-only and frozen after creation to avoid triggering dispatch-service ETA recompute, reassignment, or Order-sync.
jobs:read jobs:write Read dispatch jobs
Add-on callers: Narrowed through the owning device (DeviceId). Records whose device has no group ids stay visible to everyone.
- Supports
from/to; default last 30 days, max 31-day span.
GETRead
List (GET /v1/jobs), query (POST /v1/jobs/query) and fetch one (GET /v1/jobs/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
number | number | |
name | string | Job name. Required on create. |
reference | string | |
status | string | |
device_id | string | |
user_id | string | |
assignment_type | string (VEHICLE | DRIVER) | How the job is assigned. Optional (defaults to VEHICLE). Assignment is optional overall — the three shapes are: set device_id for a vehicle-assigned job, user_id for a driver-assigned job, or omit both to create an Unassigned job. |
due_date | string (date-time) | When the job is due. Required on create and must not be in the past (ISO-8601). |
created_at | string (date-time) | |
created_by | string |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
modified_at | string (date-time) | |
modified_by | string | |
estimated_start_date | string (date-time) | |
scheduled_date | string (date-time) | |
completed_date | string (date-time) | |
notes | array of object | Job notes, forwarded as-is (PascalCase sub-keys, matching the stored/downstream shape and the read response) to the dispatch service. |
is_pre_booked | boolean | |
custom | object | Custom key/value data for app integrations. Values may be string or number. |
default_form_id | string | |
stops | array of object | Job stops, forwarded as-is (PascalCase sub-keys, matching the stored/downstream shape and the read response) to the dispatch service. Required on create: at least one stop, and each stop must have numeric Latitude and Longitude (a non-zero position). Eta/Actual/WorkOrders are read-only. |
company_id | string | |
recurring_reference_id | string | |
recurring_display_text | string | |
job_source | string | |
bus_journey_id | string | |
bus_route_id | string |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/jobs/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
number | eq in gte lte between | Number (exact match). |
name | eq in contains starts_with | String (case-insensitive). Discover valid values via GET /v1/jobs. |
reference | eq in contains starts_with | String (case-insensitive). |
status | eq in contains starts_with | String (case-insensitive). Values: Unassigned, Assigned, Dispatched, En_route_stop, Arrived_stop, Completed_stop, Completed, Cancelled, Rejected. |
device_id | eq in contains starts_with | String (exact match). |
user_id | eq in contains starts_with | String (exact match). |
assignment_type | eq in contains starts_with | String (case-insensitive). Values: VEHICLE, DRIVER. |
due_date | eq in gte lte between | Date (exact match). |
created_at | eq in gte lte between | Date (exact match). |
created_by | eq in contains starts_with | String (case-insensitive). |
modified_at | eq in gte lte between | Date (exact match). |
modified_by | eq in contains starts_with | String (case-insensitive). |
estimated_start_date | eq in gte lte between | Date (exact match). |
scheduled_date | eq in gte lte between | Date (exact match). |
completed_date | eq in gte lte between | Date (exact match). |
is_pre_booked | eq | Boolean (exact match). |
default_form_id | eq in contains starts_with | String (exact match). |
Example
POST /v1/jobs/query
{
"filters": {
"status": "Unassigned",
"id": {
"in": [
"id_5f8a1c2b9e",
"id_9c3f21a08b"
]
},
"number": {
"gte": 42.5
},
"name": {
"contains": "Truck"
}
},
"sort": "created_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (device_id, user_id, status, assignment_type, reference) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "id_5f8a1c2b9e",
"number": 42.5,
"name": "Truck 42",
"reference": "string",
"status": "Active",
"device_id": "dvc_5f8a1c2b9e",
"user_id": "use_9c3f21a08b",
"assignment_type": "VEHICLE",
"due_date": "2026-07-15T08:30:00.000Z",
"created_at": "2026-07-15T08:30:00.000Z",
"created_by": "jdoe",
"modified_at": "2026-07-15T08:30:00.000Z",
"modified_by": "string",
"estimated_start_date": "2026-07-15T08:30:00.000Z",
"scheduled_date": "2026-07-15T08:30:00.000Z",
"completed_date": "2026-07-15T08:30:00.000Z",
"notes": [
{
"Text": "string",
"Username": "string",
"Files": [
"string"
],
"Date": "2026-07-15T08:30:00.000Z"
}
],
"is_pre_booked": true,
"custom": {
"sample": {}
},
"default_form_id": "def_9c3f21a08b",
"stops": [
{
"Id": "string",
"Name": "string",
"Address": "string",
"CustomerId": "string",
"Latitude": 42.5,
"Longitude": 42.5,
"Note": "string",
"IsStartLocation": true,
"Eta": {
"StopDuration": 42.5,
"Duration": 42.5,
"Distance": 42.5,
"ArrivalDate": "2026-07-15T08:30:00.000Z",
"DepartureDate": "2026-07-15T08:30:00.000Z"
},
"Actual": {
"StopDuration": 42.5,
"Duration": 42.5,
"Distance": 42.5,
"ArrivalDate": "2026-07-15T08:30:00.000Z",
"DepartureDate": "2026-07-15T08:30:00.000Z"
},
"WorkOrders": [
{}
]
}
],
"company_id": "acme",
"recurring_reference_id": "rec_9c3f21a08b",
"recurring_display_text": "string",
"job_source": "string",
"bus_journey_id": "bus_9c3f21a08b",
"bus_route_id": "bus_9c3f21a08b"
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
POST PATCH DELETEWrite
jobs:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Create — POST /v1/jobs
Required: name, due_date, stops. Full request body — every writable field (send only what you need; the required fields must be present):
{
"name": "string",
"reference": "string",
"device_id": "string",
"user_id": "string",
"assignment_type": "VEHICLE",
"due_date": "2026-01-01T00:00:00Z",
"estimated_start_date": "2026-01-01T00:00:00Z",
"notes": [
{
"Text": "string",
"Username": "string",
"Files": [
"string"
],
"Date": "2026-01-01T00:00:00Z"
}
],
"is_pre_booked": true,
"custom": {},
"default_form_id": "string",
"stops": [
{
"Id": "string",
"Name": "string",
"Address": "string",
"CustomerId": "string",
"Latitude": 43.6532,
"Longitude": -79.3832,
"Note": "string",
"IsStartLocation": true
}
]
}
Response
{
"data": {
"id": "id_5f8a1c2b9e",
"number": 42.5,
"name": "Truck 42",
"reference": "string",
"status": "Active",
"device_id": "dvc_5f8a1c2b9e",
"user_id": "use_9c3f21a08b",
"assignment_type": "VEHICLE",
"due_date": "2026-07-15T08:30:00.000Z",
"created_at": "2026-07-15T08:30:00.000Z",
"created_by": "jdoe",
"modified_at": "2026-07-15T08:30:00.000Z",
"modified_by": "string",
"estimated_start_date": "2026-07-15T08:30:00.000Z",
"scheduled_date": "2026-07-15T08:30:00.000Z",
"completed_date": "2026-07-15T08:30:00.000Z",
"notes": [
{
"Text": "string",
"Username": "string",
"Files": [
"string"
],
"Date": "2026-07-15T08:30:00.000Z"
}
],
"is_pre_booked": true,
"custom": {
"sample": {}
},
"default_form_id": "def_9c3f21a08b",
"stops": [
{
"Id": "string",
"Name": "string",
"Address": "string",
"CustomerId": "string",
"Latitude": 42.5,
"Longitude": 42.5,
"Note": "string",
"IsStartLocation": true,
"Eta": {
"StopDuration": 42.5,
"Duration": 42.5,
"Distance": 42.5,
"ArrivalDate": "2026-07-15T08:30:00.000Z",
"DepartureDate": "2026-07-15T08:30:00.000Z"
},
"Actual": {
"StopDuration": 42.5,
"Duration": 42.5,
"Distance": 42.5,
"ArrivalDate": "2026-07-15T08:30:00.000Z",
"DepartureDate": "2026-07-15T08:30:00.000Z"
},
"WorkOrders": [
{}
]
}
],
"company_id": "acme",
"recurring_reference_id": "rec_9c3f21a08b",
"recurring_display_text": "string",
"job_source": "string",
"bus_journey_id": "bus_9c3f21a08b",
"bus_route_id": "bus_9c3f21a08b"
},
"meta": {
"request_id": "req_abc123"
}
}
Update — PATCH /v1/jobs/{id}
Partial update: send only the fields you want to change (the same writable fields as create, minus create-only ones). Returns the updated record in the same envelope as above.
Delete — DELETE /v1/jobs/{id}
Removes the record. Returns the deleted record's id.
Tracker typesGET
Global device tracker-type catalog (device category, docs and support links; shared reference data, no tenant scoping).
devices:read Read devices and their live status
Add-on callers: Not group-scoped — Reference data; no group dimension.
GETRead
List (GET /v1/tracker-types), query (POST /v1/tracker-types/query) and fetch one (GET /v1/tracker-types/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
name | string | |
display_name | string | |
device_category | string |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
description | string | |
image_url | string | |
portal_link | string | |
setup_link | string | |
support_email | string | |
support_phone | string | |
trax_pricing | number | |
geotab_custom_pricing | number | |
training | number | |
sla_documentation_link | string | |
accessories_link | string | |
installation_document_link | string | |
partner_installation_video_link | string | |
troubleshooting_document_link | string | |
partner_video_link | string | |
data_plan_mb | number | |
features | array of object | Tracker-type feature list, forwarded as-is per stored item shape. |
crm_product | object, nullable | CRM product/SKU mapping, forwarded as-is. |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/tracker-types/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
name | eq in contains starts_with | String (exact match). Discover valid values via GET /v1/tracker-types. |
display_name | eq in contains starts_with | String (case-insensitive). |
device_category | eq in contains starts_with | String (case-insensitive). |
description | eq in contains starts_with | String (case-insensitive). |
support_email | eq in contains starts_with | String (case-insensitive). |
support_phone | eq in contains starts_with | String (case-insensitive). |
Example
POST /v1/tracker-types/query
{
"filters": {
"name": {
"in": [
"Truck 42",
"Truck 42 2"
]
},
"description": {
"contains": "Sample"
}
},
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (name) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"name": "Truck 42",
"display_name": "string",
"device_category": "string",
"description": "Sample description.",
"image_url": "string",
"portal_link": "string",
"setup_link": "string",
"support_email": "string",
"support_phone": "string",
"trax_pricing": 42.5,
"geotab_custom_pricing": 42.5,
"training": 42.5,
"sla_documentation_link": "string",
"accessories_link": "string",
"installation_document_link": "string",
"partner_installation_video_link": "string",
"troubleshooting_document_link": "string",
"partner_video_link": "string",
"data_plan_mb": 42.5,
"features": [
{}
],
"crm_product": {}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
Custom mapsGET
Custom (Indoor/Web) map overlays for a company's locations, tenant-scoped.
maps:read
Add-on callers: Not group-scoped — Company-wide map overlays; no group dimension.
GETRead
List (GET /v1/custom-maps), query (POST /v1/custom-maps/query) and fetch one (GET /v1/custom-maps/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
map_name | string | |
name | string | |
type | string | |
web_url | string, nullable | |
indoor_image_url | string, nullable |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
order | string | |
company_id | string | |
location_name | string | |
location_lat | number, nullable | |
location_lng | number, nullable | |
indoor_rotation | number, nullable | |
indoor_devices | array of object | |
indoor_beacons | array of object | |
indoor_scale | number, nullable | |
indoor_image_width | number, nullable | |
indoor_image_height | number, nullable |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/custom-maps/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
map_name | eq in contains starts_with | String (case-insensitive). |
name | eq in contains starts_with | String (case-insensitive). Discover valid values via GET /v1/custom-maps. |
type | eq in contains starts_with | String (case-insensitive). Values: Indoor, Web. |
order | eq in gte lte between | Number (exact match). |
company_id | eq in contains starts_with | String (exact match). |
location_name | eq in contains starts_with | String (case-insensitive). |
Example
POST /v1/custom-maps/query
{
"filters": {
"type": "Indoor",
"id": {
"in": [
"id_5f8a1c2b9e",
"id_9c3f21a08b"
]
},
"order": {
"gte": 42.5
},
"name": {
"contains": "Truck"
}
},
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (id, type) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "id_5f8a1c2b9e",
"map_name": "string",
"name": "Truck 42",
"type": "string",
"web_url": "string",
"indoor_image_url": "string",
"order": "string",
"company_id": "acme",
"location_name": "string",
"location_lat": 42.5,
"location_lng": 42.5,
"indoor_rotation": 42.5,
"indoor_devices": [
{
"id": "id_5f8a1c2b9e",
"left": 42.5,
"top": 42.5,
"device_placed": true
}
],
"indoor_beacons": [
{
"id": "id_5f8a1c2b9e",
"left": 42.5,
"top": 42.5,
"device_placed": true
}
],
"indoor_scale": 42.5,
"indoor_image_width": 42.5,
"indoor_image_height": 42.5
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
UsersGETPOSTPATCHDELETE
All users (from the users collection, not just drivers; filter with is_driver to narrow); credentials and security state are never exposed.
users:read users:write
Add-on callers: Narrowed to the user's viewing groups via ViewingGroups. Records with no group ids stay visible to everyone.
GETRead
List (GET /v1/users), query (POST /v1/users/query) and fetch one (GET /v1/users/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
username | string | Login username. Required on create; create-only. A password is auto-generated when omitted. |
first_name | string | |
last_name | string | |
full_name | string, nullable | |
is_driver | boolean |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
group_ids | array of string | Group ids the user belongs to. Required on create — at least one group must be supplied. |
email | string | |
phone | string | |
units | string | |
language | string | |
user_type | string | User role. Optional — defaults to Driver; an unrecognised value is rejected on create with "Invalid UserType". |
employee_id | string | |
created_at | string (date-time) | |
last_login | string (date-time) | |
company_id | string | |
license_number | string | |
license_state | string | |
license_country | string | |
working_hours | object | Per-day working-hours schedule, forwarded as-is (e.g. { Mon: { active, hours: { from, to } }, … }). |
time_zone | string | |
photo_url | string | |
telegram_chat_id | string | |
region_ids | array of string | |
business_group_ids | array of string | |
people_group_ids | array of string | |
can_assign_job_itself | boolean | |
default_view | string | |
fetch_location_from_mobile | boolean | |
feature_preview | boolean | |
supervisor_ids | array of string | |
driver_app_data | object, nullable | Driver app data — check-in/out, breaks, work-time tracking, forwarded as-is. |
map_provider | string | |
custom_fields | object | Tenant-defined custom field values, keyed by field name, forwarded as-is. |
driver_identification | string | |
verification_phone_number | string | |
show_self_data | boolean | |
comments | string | |
live_notification_settings | object, nullable | Live-notification preferences, forwarded as-is. |
switchboard_id | string | |
hos_enabled | boolean | |
hos_exempted | boolean | |
rule_set | string | |
us_hos_cycle | string | |
home_terminal_name | string | |
home_terminal_address | object, nullable | Home-terminal location ({ Location: { latitude, longitude }, LocationName }), forwarded as-is. |
exemption_annotation | string | |
yard_move_allowed | boolean | |
personal_conveyance_allowed | boolean | |
pinned_add_in_ids | array of string |
Relationships (?include=)
Expand with ?include=x,y.
| Name | Expands to | Notes |
|---|---|---|
groups | Array of Groups | Array of Groups (empty if none) |
Filters
Filter via POST /v1/users/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
id | eq in contains starts_with | String (exact match). |
username | eq in contains starts_with | String (case-insensitive). |
first_name | eq in contains starts_with | String (case-insensitive). |
last_name | eq in contains starts_with | String (case-insensitive). |
is_driver | eq | Boolean (exact match). |
group_ids | eq in | Array of string (exact match). |
email | eq in contains starts_with | String (case-insensitive). |
phone | eq in contains starts_with | String (case-insensitive). |
units | eq in contains starts_with | String (case-insensitive). |
language | eq in contains starts_with | String (case-insensitive). |
user_type | eq in contains starts_with | String (case-insensitive). Values: Driver, End Customer, EndUser, General User, Passenger, Technician. |
employee_id | eq in contains starts_with | String (case-insensitive). |
created_at | eq in gte lte between | Date (exact match). |
last_login | eq in gte lte between | Date (exact match). |
company_id | eq in contains starts_with | String (exact match). |
license_number | eq in contains starts_with | String (case-insensitive). |
license_state | eq in contains starts_with | String (case-insensitive). |
license_country | eq in contains starts_with | String (case-insensitive). |
Example
POST /v1/users/query
{
"filters": {
"user_type": "Driver",
"id": {
"in": [
"id_5f8a1c2b9e",
"id_9c3f21a08b"
]
},
"created_at": {
"gte": "2026-07-15T08:30:00.000Z"
},
"username": {
"contains": "jdoe"
}
},
"sort": "created_at:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (username, is_driver, group_id) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "id_5f8a1c2b9e",
"username": "jdoe",
"first_name": "Jane",
"last_name": "Doe",
"full_name": "string",
"is_driver": true,
"group_ids": [
"grp_1a2b3c4d5e"
],
"email": "jdoe@example.com",
"phone": "+1-555-0142",
"units": "metric",
"language": "en",
"user_type": "string",
"employee_id": "emp_9c3f21a08b",
"created_at": "2026-07-15T08:30:00.000Z",
"last_login": "2026-07-15T08:30:00.000Z",
"company_id": "acme",
"license_number": "D1234-56789",
"license_state": "ON",
"license_country": "CA",
"working_hours": {},
"time_zone": "string",
"photo_url": "string",
"telegram_chat_id": "tel_9c3f21a08b",
"region_ids": [
"string"
],
"business_group_ids": [
"string"
],
"people_group_ids": [
"string"
],
"can_assign_job_itself": true,
"default_view": "string",
"fetch_location_from_mobile": true,
"feature_preview": true,
"supervisor_ids": [
"string"
],
"driver_app_data": {},
"map_provider": "string",
"custom_fields": {},
"driver_identification": "string",
"verification_phone_number": "string",
"show_self_data": true,
"comments": "string",
"live_notification_settings": {},
"switchboard_id": "swi_9c3f21a08b",
"hos_enabled": true,
"hos_exempted": true,
"rule_set": "string",
"us_hos_cycle": "string",
"home_terminal_name": "string",
"home_terminal_address": {},
"exemption_annotation": "string",
"yard_move_allowed": true,
"personal_conveyance_allowed": true,
"pinned_add_in_ids": [
"string"
],
"groups": [
{
"id": "grp_5f8a1c2b9e",
"name": "Truck 42"
}
]
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
POST PATCH DELETEWrite
users:write Requires the write scope. All request/response bodies use the standard { data, meta } envelope.
Create — POST /v1/users
Required: username, group_ids. Full request body — every writable field (send only what you need; the required fields must be present):
{
"username": "string",
"first_name": "string",
"last_name": "string",
"group_ids": [
"string"
],
"email": "string",
"phone": "string",
"units": "string",
"language": "string",
"user_type": "string",
"employee_id": "string",
"license_number": "string",
"license_state": "string",
"license_country": "string",
"working_hours": {
"Mon": {
"active": true,
"hours": {
"from": "09:00",
"to": "17:00"
}
}
},
"password": "string",
"time_zone": "string",
"photo_url": "string",
"region_ids": [
"string"
],
"business_group_ids": [
"string"
],
"people_group_ids": [
"string"
],
"can_assign_job_itself": true,
"default_view": "string",
"fetch_location_from_mobile": true,
"feature_preview": true,
"supervisor_ids": [
"string"
],
"driver_app_data": {},
"map_provider": "string",
"custom_fields": {},
"driver_identification": "string",
"show_self_data": true,
"comments": "string",
"live_notification_settings": {},
"hos_enabled": true,
"hos_exempted": true,
"rule_set": "string",
"us_hos_cycle": "string",
"home_terminal_name": "string",
"home_terminal_address": {
"Location": {
"latitude": 43.6532,
"longitude": -79.3832
},
"LocationName": "Main Depot"
},
"exemption_annotation": "string",
"yard_move_allowed": true,
"personal_conveyance_allowed": true,
"pinned_add_in_ids": [
"string"
]
}
Response
{
"data": {
"id": "id_5f8a1c2b9e",
"username": "jdoe",
"first_name": "Jane",
"last_name": "Doe",
"full_name": "string",
"is_driver": true,
"group_ids": [
"grp_1a2b3c4d5e"
],
"email": "jdoe@example.com",
"phone": "+1-555-0142",
"units": "metric",
"language": "en",
"user_type": "string",
"employee_id": "emp_9c3f21a08b",
"created_at": "2026-07-15T08:30:00.000Z",
"last_login": "2026-07-15T08:30:00.000Z",
"company_id": "acme",
"license_number": "D1234-56789",
"license_state": "ON",
"license_country": "CA",
"working_hours": {},
"time_zone": "string",
"photo_url": "string",
"telegram_chat_id": "tel_9c3f21a08b",
"region_ids": [
"string"
],
"business_group_ids": [
"string"
],
"people_group_ids": [
"string"
],
"can_assign_job_itself": true,
"default_view": "string",
"fetch_location_from_mobile": true,
"feature_preview": true,
"supervisor_ids": [
"string"
],
"driver_app_data": {},
"map_provider": "string",
"custom_fields": {},
"driver_identification": "string",
"verification_phone_number": "string",
"show_self_data": true,
"comments": "string",
"live_notification_settings": {},
"switchboard_id": "swi_9c3f21a08b",
"hos_enabled": true,
"hos_exempted": true,
"rule_set": "string",
"us_hos_cycle": "string",
"home_terminal_name": "string",
"home_terminal_address": {},
"exemption_annotation": "string",
"yard_move_allowed": true,
"personal_conveyance_allowed": true,
"pinned_add_in_ids": [
"string"
]
},
"meta": {
"request_id": "req_abc123"
}
}
Update — PATCH /v1/users/{id}
Partial update: send only the fields you want to change (the same writable fields as create, minus create-only ones). Returns the updated record in the same envelope as above.
Delete — DELETE /v1/users/{id}
Removes the record. Returns the deleted record's id.
Coaching sessionsGET
Driver coaching deliveries (AI or manual): who was coached, when, on which safety events, and the delivery status.
coaching:read Read driver coaching sessions
Add-on callers: Narrowed through the owning device (DeviceId). Records whose device has no group ids stay visible to everyone.
- Supports
from/to; default last 30 days.
GETRead
List (GET /v1/coaching-sessions), query (POST /v1/coaching-sessions/query) and fetch one (GET /v1/coaching-sessions/{id}).
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
id | string | |
driver_id | string | |
device_id | string | |
coaching_date | string (date-time) | |
method | string | |
coach_id | string | |
status | string | |
digest_type | string | |
exceptions_coached | string | |
badges | string | |
rule_ids | array of string | |
is_acknowledged | boolean | |
created_at | string (date-time) | |
updated_at | string (date-time) |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
coaching_notes | string |
Relationships (?include=)
Expand with ?include=x,y.
None.
Filters
Filter via POST /v1/coaching-sessions/query with a JSON filters object. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g. {"gte": 10}.
| Filter | Operators | Notes |
|---|---|---|
driver_id | eq in | String (exact match). |
device_id | eq in | String (exact match). |
coaching_date | eq in gte lte between | Date (exact match). |
method | eq in | String (case-insensitive). Values: AI, MANUAL. |
coach_id | eq in | String (exact match). |
status | eq in | String (case-insensitive). Values: Pending, WaitingForSafeWindow, Delivering, Completed, Cancelled, Failed. |
digest_type | eq in | String (case-insensitive). Values: daily, weekly, monthly. |
is_acknowledged | eq | Boolean (exact match). |
Example
POST /v1/coaching-sessions/query
{
"filters": {
"method": "AI",
"driver_id": {
"in": [
"drv_7a1e4c8f02",
"drv_9c3f21a08b"
]
},
"coaching_date": {
"gte": "2026-07-15T08:30:00.000Z"
}
},
"sort": "coaching_date:desc",
"limit": 20
}
Request controls: sort, from/to (time-series), limit, cursor, count — documented in the API Reference.
A few bare-equality query params (driver_id, device_id, status, method) are also accepted on GET for backwards-compatibility; the filters body above is the complete mechanism.
Example response
{
"data": [
{
"id": "id_5f8a1c2b9e",
"driver_id": "drv_7a1e4c8f02",
"device_id": "dvc_5f8a1c2b9e",
"coaching_date": "2026-07-15T08:30:00.000Z",
"method": "string",
"coach_id": "coa_9c3f21a08b",
"status": "Active",
"digest_type": "string",
"exceptions_coached": "string",
"badges": "string",
"rule_ids": [
"string"
],
"is_acknowledged": true,
"created_at": "2026-07-15T08:30:00.000Z",
"updated_at": "2026-07-15T08:30:00.000Z",
"coaching_notes": "string"
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
Device statusGET
Live current-state sub-resource of a device — position, speed, heading, ignition.
devices:read Read devices and their live status
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
device_id | string | |
latitude | number | |
longitude | number | |
speed_kmh | number | |
heading | number | |
is_ignition_on | boolean | |
is_moving | boolean | |
is_communicating | boolean | |
updated_at | string (date-time) |
Example response
{
"data": {
"device_id": "dvc_5f8a1c2b9e",
"latitude": 43.6532,
"longitude": -79.3832,
"speed_kmh": 64.2,
"heading": 180,
"is_ignition_on": true,
"is_moving": true,
"is_communicating": true,
"updated_at": "2026-07-15T08:30:00.000Z"
},
"meta": {
"request_id": "req_abc123"
}
}
Driver summaryGET
Aggregated per-driver rollup over a date range — trips, distance, exceptions, safety score.
summaries:read Read driver and vehicle summaries
- Aggregation over a date range;
from/toas YYYY-MM-DD, default yesterday, max 31 days.
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
driver_id | string | |
driver_name | string | |
driver_email | string | |
period | SummaryPeriod | |
distance | number | Distance in kilometres. |
driving_duration | number | Driving time in seconds. |
idling_duration | number | Idling time in seconds. |
trip_count | number | |
max_speed_kmh | number | |
avg_speed_kmh | number | |
idling_ratio | number | Idling over driving + idling time, as a fraction 0–1. |
safety_score | number | Safety score 0–100; higher is safer. |
risk_band | string | |
p_accident | number | Modelled accident probability, 0–1. |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
avg_trip_dist_km | number | |
speeding_duration | number | Speeding time in seconds. |
speeding_event_count | number | |
harsh_braking_count | number | |
harsh_acceleration_count | number | |
seatbelt_violations | number | |
idling_event_count | number | |
exceptions | object | Map of name → count. |
after_hours_driving_duration | number | After-hours driving time in seconds. |
after_hours_distance | number | After-hours distance in kilometres. |
after_hours_stop_duration | number | After-hours stopped time in seconds. |
speeding_ratio | number | Speeding over driving time, as a fraction 0–1. |
after_hours_ratio | number | After-hours over driving time, as a fraction 0–1. |
braking_per_100km | number | Harsh-braking events per 100 kilometres. |
accel_per_100km | number | Harsh-acceleration events per 100 kilometres. |
speeding_pct | number | Same quantity as speeding_ratio, as a percentage 0–100. |
idling_pct | number | Same quantity as idling_ratio, as a percentage 0–100. |
after_hours_pct | number | Same quantity as after_hours_ratio, as a percentage 0–100. |
Example response
{
"data": {
"driver_id": "drv_7a1e4c8f02",
"driver_name": "Jane Doe",
"driver_email": "jane.doe@example.com",
"period": {
"from": "2026-06-01",
"to": "2026-06-07"
},
"distance": 42.5,
"driving_duration": 42.5,
"idling_duration": 42.5,
"trip_count": 42.5,
"max_speed_kmh": 96.3,
"avg_speed_kmh": 58.1,
"idling_ratio": 42.5,
"safety_score": 42.5,
"risk_band": "string",
"p_accident": 42.5,
"avg_trip_dist_km": 42.5,
"speeding_duration": 42.5,
"speeding_event_count": 42.5,
"harsh_braking_count": 42.5,
"harsh_acceleration_count": 42.5,
"seatbelt_violations": 42.5,
"idling_event_count": 42.5,
"exceptions": {
"speeding": 3
},
"after_hours_driving_duration": 42.5,
"after_hours_distance": 42.5,
"after_hours_stop_duration": 42.5,
"speeding_ratio": 42.5,
"after_hours_ratio": 42.5,
"braking_per_100km": 42.5,
"accel_per_100km": 42.5,
"speeding_pct": 42.5,
"idling_pct": 42.5,
"after_hours_pct": 42.5
},
"meta": {
"request_id": "req_abc123",
"period": {
"from": "2026-06-01",
"to": "2026-06-07"
}
}
}
Vehicle summaryGET
Aggregated per-vehicle rollup over a date range — distance, durations, odometer, drivers.
summaries:read Read driver and vehicle summaries
- Aggregation over a date range;
from/toas YYYY-MM-DD, default yesterday, max 31 days.
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
device_id | string | |
license_plate | string | |
vin | string | |
period | SummaryPeriod | |
distance | number | Distance in kilometres. |
driving_duration | number | Driving time in seconds. |
idling_duration | number | Idling time in seconds. |
trip_count | number | |
avg_speed_kmh | number | |
idling_ratio | number | Idling over driving + idling time, as a fraction 0–1. |
odometer_km | number |
Optional fields (?fields=)
Add these with ?fields=a,b — they ship on top of the defaults.
| Key | Type | Description |
|---|---|---|
after_hours_driving_duration | number | After-hours driving time in seconds. |
after_hours_distance | number | After-hours distance in kilometres. |
after_hours_stop_duration | number | After-hours stopped time in seconds. |
work_driving_duration | number | On-schedule driving time in seconds. |
work_distance | number | On-schedule distance in kilometres. |
work_stop_duration | number | On-schedule stopped time in seconds. |
daily_distance_km_ecu | number | |
engine_hours_total | number | |
driver_change_count | number | |
drivers_on_vehicle | array of string | |
after_hours_ratio | number | After-hours over driving time, as a fraction 0–1. |
Example response
{
"data": {
"device_id": "dvc_5f8a1c2b9e",
"license_plate": "ABC-1234",
"vin": "1FTFW1E5XKF12345",
"period": {
"from": "2026-06-01",
"to": "2026-06-07"
},
"distance": 42.5,
"driving_duration": 42.5,
"idling_duration": 42.5,
"trip_count": 42.5,
"avg_speed_kmh": 58.1,
"idling_ratio": 42.5,
"odometer_km": 104532.7,
"after_hours_driving_duration": 42.5,
"after_hours_distance": 42.5,
"after_hours_stop_duration": 42.5,
"work_driving_duration": 42.5,
"work_distance": 42.5,
"work_stop_duration": 42.5,
"daily_distance_km_ecu": 42.5,
"engine_hours_total": 42.5,
"driver_change_count": 42.5,
"drivers_on_vehicle": [
"drv_7a1e4c8f02"
],
"after_hours_ratio": 42.5
},
"meta": {
"request_id": "req_abc123",
"period": {
"from": "2026-06-01",
"to": "2026-06-07"
}
}
}
IFTA summaryGET
Distance by vehicle × jurisdiction × month, aggregated from trips, for IFTA / state-mileage reporting.
ifta:read Read IFTA / state-mileage summaries
- List endpoint (keyset pagination); supports
from/to(default: current UTC month to date; max 31 days) and an optionaldevice_idfilter.
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
device_id | string | |
jurisdiction | string | US state / CA province of the trip's start position. |
country | string | |
month | string | YYYY-MM (UTC). |
distance_km | number | Summed trip distance for the vehicle in that jurisdiction and month (km). |
trip_count | integer |
Example response
{
"data": [
{
"device_id": "dvc_5f8a1c2b9e",
"jurisdiction": "ON",
"country": "CA",
"month": "2026-06",
"distance_km": 42.5,
"trip_count": 3
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
Media (video & camera)GET
Camera/DVR actions for a device (POST, not CRUD). Each endpoint returns a DIFFERENT shape: POST /media/recordings → available recording segments (RecordingSegment[], shown below — footage windows with NO url); POST /media/live-streams and POST /media/historical-streams → stream sources (LiveSource[], with a stream url); POST /media/video-requests and POST /media/snapshot-requests → an async { task_id }; GET /media/tasks/{task_id} → a MediaTaskStatus whose result is MediaItem[] (the finished clips/snapshots, WITH url/full_url/screenshot); POST /media/wake → { success }. All delegate to trax-client-service, which owns device/tenant validation and dispatch to the camera provider.
media:read Read camera media — live/historical stream URLs, recordings, and media task status
- Video/snapshot/wake need
media:write; streams/recordings/task-status needmedia:read. Receiving recorded footage is a two-step flow:POST /media/recordingsis an INDEX — it lists the available segments (below), which are NOT downloadable files; take a segment'sdate_fromand either WATCH it withPOST /media/historical-streams(returns a playable streamurl) or DOWNLOAD a clip withPOST /media/video-requests(async — pollGET /media/tasks/{task_id}untilstatusiscompleted, then readresult, aMediaItem[]withurl/full_url/screenshot). The DVR generates media on demand, which is why the recordings list has no urls. Every shape (RecordingSegment,LiveSource,MediaItem) carries arawfield with the provider's full record verbatim, so provider-specific fields are never hidden. See the API Reference for theLiveSource/MediaItem/MediaTaskStatusschemas.
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
device_id | string | |
channel | integer | |
date_from | string (date-time) | |
date_to | string (date-time) | |
stream_type | integer | |
raw | object | The provider's full recording record verbatim; shape varies by camera provider. |
Example response
{
"data": [
{
"device_id": "dvc_5f8a1c2b9e",
"channel": 3,
"date_from": "2026-07-15T08:30:00.000Z",
"date_to": "2026-07-15T08:30:00.000Z",
"stream_type": 3,
"raw": {}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
GeocodingGET
Reverse-geocode coordinates to addresses plus the company's containing zone. POST /geocoding/addresses with { coordinates: [{ lat, lng }] }; the response array is parallel to the input coordinates.
geocoding:read Reverse-geocode coordinates to addresses and the company's containing zones
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
formatted_address | string | |
zone | object | The company zone containing the coordinate, or null if none. |
Example response
{
"data": [
{
"formatted_address": "string",
"zone": {}
}
],
"meta": {
"request_id": "req_abc123",
"count": 1,
"next_cursor": null,
"has_more": false
}
}
Text-to-SpeechGET
Send a text-to-speech audio message to StreamMax cameras. POST /tts/messages with { device_ids, text, language } — text is 150 characters or fewer, language is english or spanish. The result reports per-device success and failed (e.g. a non-StreamMax device fails individually, never reaching the provider).
tts:write Send a text-to-speech audio message to StreamMax cameras
Default fields
Always returned.
| Key | Type | Description |
|---|---|---|
success | array of string | Device ids the message was sent to. |
failed | array of object | Device ids the message could not be sent to, with an error per device (e.g. not a StreamMax device). |
Example response
{
"data": {
"success": [
"string"
],
"failed": [
{
"device_id": "dvc_5f8a1c2b9e",
"error": "string"
}
]
},
"meta": {
"request_id": "req_abc123"
}
}
CommentsGET
Comments attached to a parent entity (polymorphic ParentId, commonly a safety event), tenant-scoped, list-only, date-cursored.
comments:read
Add-on callers: Not group-scoped — Polymorphic ParentId with no ParentType to join on. requiredFilters: parent_id means a caller must already hold a parent id, and parent listings are themselves narrowed.
from/to(optional, uncapped) — no default window; these rows are long-lived state, not events.parent_id.GET /comments/{id}route.GETRead
List (
GET /v1/comments), query (POST /v1/comments/query) and fetch one (GET /v1/comments/{id}).Default fields
Always returned.
idparent_idtextcreated_atuser_iduser_full_nameOptional fields (
?fields=)Add these with
?fields=a,b— they ship on top of the defaults.updated_atis_visible_to_drivercompany_idattachmentslinkis_editableadditional_notesupdated_by_user_idRelationships (
?include=)Expand with
?include=x,y.None.
Filters
Filter via
POST /v1/comments/querywith a JSONfiltersobject. A bare value means equals (eq); a bare array means any-of (in); or use an explicit operator object, e.g.{"gte": 10}.parent_ideqincontainsstarts_withtexteqincontainsstarts_withcreated_ateqingteltebetweenuser_ideqincontainsstarts_withuser_full_nameeqincontainsstarts_withupdated_ateqingteltebetweenis_visible_to_drivereqExample
Request controls:
sort,from/to(time-series),limit,cursor,count— documented in the API Reference.A few bare-equality query params (
parent_id) are also accepted onGETfor backwards-compatibility; thefiltersbody above is the complete mechanism.Example response
Open in API Reference → · Back to top