Click or drag to resize
POST /hos_events
Print this page
Description

This service is used to log one or more new HOS (hours of service) status events or to update existing events for the authenticated driver.

A revision history for each event is stored internally, but it is not publicly exposed.

Request

For any event:

  • If an Id is not specified, then the service creates a new status event that matches the description.
  • If an Id is specified, then the service interprets the request as a create or update request. If no event exists with the specified Id, then an event will be created. Otherwise, the existing event will be updated.
Note Note

Standard driver status events (OffDuty, SleeperBerth, Driving, OnDutyNotDriving, and OffDutyWellSite) cannot be created with the same EventTime as other standard driver status events. However, these can be created with the same eventTime as any of the other status events.

The request body is a JSON array of event objects:

Member Type Purpose
id string (preferred but not required due to backwards compatibility) A GUID for the event, used for creating, updating or deleting a specific event.
status string Indicates the type of the event (the driver's new status). Values: OffDuty (default), Driving, OnDutyNotDriving, HoS16HourExtension, SleeperBerth, InOilfield, OffDutyWellSite, OutOilfield, WeeklyReset, SensorActive, SensorFailed, ShortWorkShiftReset, SignedEmptyDay.
eventTime string The ISO 8601 timestamp of the status change. TDE prevents assigning future times, beyond a few minutes allowed for variance among clocks.
modifiedTime string The ISO 8601 timestamp of the last modification to the event. TDE prevents assigning future times, beyond a few minutes allowed for variance among clocks.
location Address (required on create if Remarks is blank) The location where the event occurred (where the driver changed status).
Member Type Purpose
street string The street number and name of the address.
city string The city in which the address is located.
region string The region in which the address is located (e.g., state or province).
postalCode string The postal code or zip code of the address.
lat double (required for POST) The latitude of the address in decimal degrees.
lon double (required for POST) The longitude of the address in decimal degrees.
bearingFromStreet double? The side of the road on which the address is located, indicated as an angle in decimal degrees (0 is north, 90 is east).
suburb string The suburb in which the address is located.
This field can be updated through the API.
signatureId string Unique identifier for the driver's signature data. If set, this indicates that the event has been signed by the driver.
remarks string (required on create if Location is blank) An arbitrary string of notes attached to the event. This field can be updated through the API.
properties EventProperties (optional) Includes any additional information related to the event.
custom JSON object (optional) Contains one or more custom key-value pairs to hold additional data associated with the event or its location. Each POST updates the contents of this field and adds any new set of key-value pairs. To delete a key, set it to null explicitly, as foo:null.
version int (read-only) Version number that increments with each editing of the event (1 indicates the original version).
odoDetails Odometer Odometer data supports compliance reporting and differentiates between unit-supplied and driver-supplied data.
Member Type Purpose
unitId int (set if the user has an assigned, reporting unit at the event time, overwriting any Id set by user) The Id of the unit that is associated with the event.
odo double The odometer reading as reported by the unit (via the server) or user. If the driver has an assigned unit that has reported data within the last 4 minutes, the value will come from the server.
time string The ISO 8601 timestamp for when the unit or user reported the odometer reading.
source string The source of the odometer data. Values: unit, user (must specify "user" when updating via API).

Response

On success, the response body contains a JSON array of event objects. There is one entry in the array for each entry in the request body. Only the eventTime and id fields of the events will be returned. If a transaction error occurs while processing a particular event object, then that object will include additional fields specified by the error object.

If the request fails, an Error Response is generated.