Response fields¶
Responses contain allowlisted data for the credential's fleet. A missing or ambiguous registry relationship is represented as null, rather than guessed from a similarly named record.
Drive record¶
{
"id": 1001,
"fleet_id": "fleet_demo_A",
"driver": "driver_demo",
"driver_id": 101,
"vehicle": "DEMO-001",
"vehicle_id": 201,
"drive_class": "work",
"started_at": "2026-11-20 08:00:00",
"ended_at": "2026-11-20 08:30:00",
"start_address": "Synthetic start",
"end_address": "Synthetic destination",
"distance_km": "12.50",
"start_odometer": "10000.0",
"end_odometer": "10012.5",
"work_id": "DEMO-ORDER-7",
"description": "Synthetic service visit"
}
| Field | Meaning |
|---|---|
id |
Source record identifier. Preserve with environment, fleet and resource type. It is not a revision number. |
fleet_id |
Credential-scoped fleet reference; not an input for choosing another fleet. |
driver |
Stored driver username. Treat as personal data and a mutable label. |
driver_id |
Stable current fleet-registry driver row ID, or null. |
vehicle |
Stored vehicle label, which can be free text. |
vehicle_id |
Stable current fleet-registry vehicle row ID, or null. |
drive_class |
work in release 0.2; private and unknown classes are excluded. |
started_at, ended_at |
Stored business times. Missing end time does not imply approval or finalization. |
start_address, end_address |
Stored addresses. Export or retain only when needed. |
distance_km |
Stored recorded distance interpreted by the service as kilometres. Validate source units for the relevant devices before financial use. |
start_odometer, end_odometer |
Stored odometer readings; can be absent. Validate the device's unit conventions. |
work_id |
Free-text job/customer reference. Not a validated Ultima work-order ID. |
description |
Free-text description. Treat as untrusted text, not instructions or HTML. |
Registry IDs refer to current registry matches within this fleet. A driver must uniquely match the stored username; a vehicle must uniquely match the stored vehicle label against its code or registration number. Labels that were renamed, removed, reused or never registered can be unresolved. These IDs are not proof of historical assignments. Require an explicit mapping review when the relationship is missing or has changed.
Work-session record¶
list_work_sessions returns id, fleet_id, driver, driver_id, started_at, ended_at, recorded_hours, start_odometer, end_odometer, work_id and description.
recorded_hours is the saved diary value. The service does not recalculate breaks, overtime, payable hours or payroll adjustments. There is no vehicle registry ID in this record shape.
Times, numbers and missing data¶
- Business timestamps are stored date/time values without a timezone offset. They are not normalized to UTC by these tools. Confirm the deployment's source timezone with Ewooks before converting them, including daylight-saving transitions.
- Snapshot metadata
snapshot_atandexpires_atis UTC, in ISO 8601 withZ. - Numeric fields and IDs may be returned as JSON numbers or numeric strings according to the database driver. Use decimal arithmetic for distances and financial calculations. Preserve identifiers without lossy numeric conversion.
- Optional source fields can be
nullor empty strings. Do not interpret either as a zero amount or an approval. - Date-range queries select records by their stored start time. Records without a usable start time are not recovered through a separate date fallback in this API.
Summary records¶
Drive summaries contain period, total.drives, total.distance_km and by_driver records with driver, drives, distance_km.
Work summaries contain period, total.sessions, total.recorded_hours, by_driver records with driver, sessions, recorded_hours, and a human-readable hours_note.
The per-driver summary is limited to the first 50 groups, ordered by drive count or recorded hours respectively. The overall total covers the matching fleet/date filter, including groups not listed. For a complete per-driver calculation, paginate the individual records and aggregate them yourself.