Programming Guide to the Hours of Service Platform

Driver Histories

The Driver History events on his/her Logs are stored and accessed using the driverHistories endpoint.  This API provides access to Driving History information such as the Record Status, Event Record Origin, and Event Type for records which are either recorded automatically, created manually by a Driver, or created manually by an Authorized Personnel.

  1. Driver’s Duty Status change – OnDuty, OffDuty, Driving, Sleeper, WaitingAtSite
  2. Intermediate Log – recorded at a set interval while the driver is driving
  3. Personal Driving Status – Yard Moves or Personal Conveyance
  4. Certification of Driver Daily
  5. Eld Login/Logout Activity – automatically recorded by the ELD
  6. Eld Login/Logout Activity – automatically recorded by the ELD
  7. Malfunction and Diagnostic Events – automatically recorded by the ELD

The Driver History events recorded using this endpoint are the driver’s log and are transferred, after suitable formatting, to the FMCSA upon request.  Events such as OnDuty or OffDuty records from a timekeeping system may also be entered into a driver’s log using this api.  Events in Driver History should never be deleted.  This API is intended to contain the driver’s permanent record of Driver History events.

Driver Histories are automatically deleted after a specific period of time following the data retention policy.

Fields

Tag Data Type Required Description
accountId Long No The id of the Account that owns this record.
assetId Long No The id of the Vehicle that the Driver used to perform this event.
autoEventEndTimestamp Text No Date and time when the event has ended. This is only present on Auto Driving events
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
canAdlHoursDriving Duration No Canadian Rules for Additional Driving hours 
canAdlHoursOffDuty Duration No Canadian Rules for Additional Off Duty hours 
canAdlHoursOnDuty Duration No Canadian Rules for Additional On Duty hours 
canAdlHoursSleeper Duration No Canadian Rules for Additional Sleeper hours 
canOffDutyTimeDeferred Duration No Canadian Rules for the amount of time deferred by the driver.
canAdlHoursWorkShiftStart Text No Canadian Additional hours work shift start time.
canAdlHoursWorkShiftEnd Text  No Canadian Additional hours work shift end time.
certificationCount Integer No Incremented every time a Driver certifies a Driver Daily
certificationDate Text No Date and Time when the Driver Daily has been certified.
Note: Format must be in (YYYY-MM-DD)
changeRequestedBy Long No The id of the User who is requesting an edit from the Driver. This is not returned for events that have not been edited.
changeRequestedByName Character (255) No The name of the User who is requesting an edit from the Driver. This is not returned for events that have not been edited.
coDriverUserIds Character No List of ids of co-drivers
coDriverUsernames Character No List of email addresses of co-drivers
cycleResetTimestamp Text No Date and time when the cycle reset has been taken.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
dataCheck Integer Auto The hexadecimal representation of the event’s output 8-bit byte.
deletedAt Text No The date and time when an event is soft deleted.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
diagnosticIndicator Boolean No Indicates if a device has a Data Diagnostic
distanceLastGpsKm Double Precision No The distance recorded in the Last GPS update of the Driver in KM unit 
driverEdit Boolean No Indicates if the event has been edited.
editReason Character (255) No A reason to be entered when the Driver edits the event, can be customized or from a list of of pre-defined reasons:

  • Rental Vehicle no ELD on-board
  • ELD Device Failure
  • Missing GPS Location
  • Incorrect Status Selected
  • Incorrect Data Entered
  • Driver Not Logged On
  • Engineers Road Test
engineHours Interval No The number of hours the engine has been running.
eventSequenceIdentifier Integer No The sequence identifier of the event
eventTime Text Yes Date and time of event change
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
eventType Character (255) Yes

Examples of eventType values are:

  • OffDuty
  • Sleeper
  • Driving
  • OnDuty
  • WaitingAtSite
  • Remark
  • Inter
  • InterRP
  • PersonalUse
  • YardMoves
  • ClearPU
  • ClearYM
  • Certify
  • Login
  • Logout
  • PowerOn
  • PowerOnRP
  • PowerOff
  • PowerOffRP
  • MalPower
  • MalSync
  • MalTime
  • MalPos
  • MalRecord
  • MalTransfer
  • MalOther
  • MalPowerClear
  • MalSyncClear
  • MalTimeClear
  • MalPosClear
  • MalRecordClear
  • MalTransferClear
  • MalOtherClear
  • DiagPower
  • DiagSync
  • DiagMissing
  • DiagTransfer
  • DiagUnidentified
  • DiagOther
  • DiagPowerClear
  • DiagSyncClear
  • DiagMissingClear
  • DiagTransferClear
  • DiagUnidentifiedClear
  • DiagOtherClear
excludeDrivingEndTimestamp Text No

This is the endtime stamp for the excludeDriving for eventType enum.
gpsSource Character (255) No The GPS source of the Driver History. Can be any of the following values:

  • MOBILE_DEVICE
  • VBUS_DEVICE
  • EITHER_DEVICE
id Auto-incremented Long Auto Unique Identifier
lastChangedDate Text Auto Auto-generated timestamp of the last change made to this record
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
latitude Double Precision No Latitude of the location if available.
location Character (255) No The address where event was initiated. 
longitude Double Precision No Longitude of the location if available.
malfunctionIndicator Boolean No Indicates if a device has an ELD Malfunction 
note Text (unlimited) No An optional note entered by driver associated with this event. 
odometerKm Double Precision No Odometer value of the Vehicle during this event.
odometerSource Character (255) No

Odometer source can be:

  • ECU
  • Manual
  • GPS
recordOrigin Character (255) No

Record origin can be:

  • Auto
  • Driver
  • EditRequest
  • FromUnidentifiedDriver
recordStatus Character (255) Yes

Record Status can be:

  • Active
  • InactiveChanged
  • InactiveChangeRequested
  • InactiveChangeRejected
regulationMode Character No

Indicates the Regulation Mode of the Vehicle used in the current Driver History. Can either be “ELD” or “AOBRD”
relatedUuid Text (unlimited) No The UUID of the Driver History that is related to the current record.
shippingDocsManifestNo Character (255) No The Shipping Document’s Manifest number
speedKph Double Precision No The speed of the Vehicle at the time of the current event
state Character (25) No The state where the event was recorded. This is to be used for State Mileage calculations. Can either be one of the following state codes:

  • USA: AL, AK, AR, AZ, CA, CO, CT, DC, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY
  • USA Protectorates: AS, DC, GU, MP, PR, VI
  • Canada: AB, BC, MB, NB, NF, NS, NT, ON, PE, QC, SK, YT
  • Mexico: MEX_AG, MEX_BN, MEX_BS, MEX_CH, MEX_CI, MEX_CL, MEX_CP, MEX_CS, MEX_DF, MEX_DG, MEX_GE, MEX_GJ, MEX_HD, MEX_JA, MEX_MC, MEX_MR, MEX_MX, MEX_NA, MEX_NL, MEX_OA, MEX_PU, MEX_QE, MEX_QI, MEX_SI, MEX_SL, MEX_SO, MEX_TA, MEX_TB, MEX_TL, MEX_VC, MEX_YU, MEX_ZA
trailerNumbers Character (255) No  The Trailer names associated with the current PowerOn or PowerOff event. 
useCycleReset Boolean No Indicates when a driver has taken a cycle reset.
userId Long Yes The id of the Driver who performed this Driver History event.
username Character (255) Yes The username of the Driver who performed this Driver History event. 
uuid Character Yes Universally unique identifier
validBeginTime Text Yes Date and time when the event is created
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z) 
validEndTime Text No Date and time when the event ended
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
vin Character (255) No The Vehicle Identification Number of the Vehicle associated with the event.

Create OnDuty, Not Driving event

API PATH: /api/v2/driverHistories
METHOD: POST
REQUIRED FIELDS: userId, uuid, recordStatus, username, eventType, recordOrigin, eventTime
RECOMMENDED FIELDS: all required fields, validBeginTime, validEndTime
EXAMPLE REQUEST: 
[
  {
    "userId": 1253132,
    "uuid": "96e2d49f-abe4-4a65-a808-5d57917f93d9",
    "vin": "1M8GDM9AXKP042000",
    "recordStatus": "Active",
    "username": "johndoe@mail.com",
    "eventType": "OnDuty",
    "recordOrigin": "Driver",
    "eventTime": "2016-11-10T01:28:15.229Z"
  }
]
EXAMPLE RESPONSE: 
[
  {
    "userId": 1253143,
    "uuid": "96e2d49f-abe4-4a65-a808-5d57917f93d9",
    "driverEdit": false,
    "useCycleReset": true,
    "vin": "1M8GDM9AXKP042000",
    "recordStatus": "Active",
    "username": "johndoe@mail.com",
    "malfunctionIndicator": false,
    "diagnosticIndicator": false,
    "dataCheck": 86,
    "eventType": "OnDuty",
    "recordOrigin": "Driver",
    "eventTime": "2016-11-10T01:28:15.229Z",
    "accountId": 1248692,
    "id": 5160406,
    "lastChangedDate": "2016-11-15T05:05:59.286Z"
  }
]

Create OffDuty event

API PATH: /api/v2/driverHistories
METHOD: POST
REQUIRED FIELDS: userId, uuid, recordStatus, username, eventType, recordOrigin, eventTime
RECOMMENDED FIELDS: all required fields, validBeginTime, validEndTime
EXAMPLE REQUEST: 
[
  {
    "userId": 1253132,
    "uuid": "96e2d49f-abe4-4a65-a808-5d57917f93d9",
    "vin": "1M8GDM9AXKP042000",
    "recordStatus": "Active",
    "username": "johndoe@mail.com",
    "eventType": "OffDuty",
    "recordOrigin": "Driver",
    "eventTime": "2016-11-10T01:28:15.229Z"
  }
]
EXAMPLE RESPONSE: 
[
  {
    "userId": 1253143,
    "uuid": "96e2d49f-abe4-4a65-a808-5d57917f93d9",
    "driverEdit": false,
    "useCycleReset": true,
    "vin": "1M8GDM9AXKP042000",
    "recordStatus": "Active",
    "username": "johndoe@mail.com",
    "malfunctionIndicator": false,
    "diagnosticIndicator": false,
    "dataCheck": 86,
    "eventType": "OffDuty",
    "recordOrigin": "Driver",
    "eventTime": "2016-11-10T01:28:15.229Z",
    "accountId": 1248692,
    "id": 5160406,
    "lastChangedDate": "2016-11-15T05:05:59.286Z"
  }
]

Create Driving event

API PATH: /api/v2/driverHistories
METHOD: POST
REQUIRED FIELDS: userId, uuid, recordStatus, username, eventType, recordOrigin, eventTime
RECOMMENDED FIELDS: all required fields, validBeginTime, validEndTime
EXAMPLE REQUEST: 
[
  {
    "userId": 1253132,
    "uuid": "96e2d49f-abe4-4a65-a808-5d57917f93d9",
    "vin": "1M8GDM9AXKP042000",
    "recordStatus": "Active",
    "username": "johndoe@mail.com",
    "eventType": "Driving",
    "recordOrigin": "Driver",
    "eventTime": "2016-11-10T01:28:15.229Z"
  }
]
EXAMPLE RESPONSE: 
[
  {
    "userId": 1253143,
    "uuid": "96e2d49f-abe4-4a65-a808-5d57917f93d9",
    "driverEdit": false,
    "useCycleReset": true,
    "vin": "1M8GDM9AXKP042000",
    "recordStatus": "Active",
    "username": "johndoe@mail.com",
    "malfunctionIndicator": false,
    "diagnosticIndicator": false,
    "dataCheck": 86,
    "eventType": "Driving",
    "recordOrigin": "Driver",
    "eventTime": "2016-11-10T01:28:15.229Z",
    "accountId": 1248692,
    "id": 5160406,
    "lastChangedDate": "2016-11-15T05:05:59.286Z"
  }
]

Read

API PATH: /api/v2/driverHistories
METHOD: GET
PARAMETERS: user-id – Retrieves matching records for a specific User (e.g. user-id=496650, all Users by default)
asset-id – Retrieves matching records for a specific Vehicle. Also accepts comma-separated values (e.g. asset-id=1326729, all Vehicles by default)
uuid – Retrieves matching records with the specified UUID (e.g. uuid=96e2d49f-abe4-4a65-a808-5d57917f93d9, all UUIDs by default)
home-terminal-id – Retrieves matching records whose Vehicle’s homeTerminalId matches the specified parameter (e.g. home-terminal-id=634, all terminals by default)
event-type – Retrieves matching records that have the specified Event Type (e.g. event-type=OnDuty, all Event Types by default)
note – Retrieves matching records that have the specified note (e.g. note=Authenticate, all notes by default)
record-status – Retrieves matching records that have the specified Record Status (e.g. record-status=Active, all Record Statuses by default)
record-origin – Retrieves matching records that have the specified Record Origin (e.g. record-origin=Driver, all record origins by default)
from-event-time – Retrieves matching records that occurred on or after the specified date (e.g. from-event-time=2016-07-05T03:03:10.147Z, all dates by default)
to-event-time – Retrieves matching records that occurred on or before the specified date (e.g. to-event-time=2016-07-05T03:03:10.147Z, all dates by default)
from-deleted-at – Retrieves matching records that were deleted after the specified timestamp. Setting to * will return all records. (e.g. from-deleted-at=2016-07-26T03:59:08.114Z, null by default – returns only non-deleted records)
from-change-timestamp – Retrieves records modified since the timestamp supplied (e.g. from-change-timestamp=2016-07-01T05:32:39.111Z)
to-change-timestamp – Retrieves records modified before the timestamp supplied (e.g. to-change-timestamp=2016-07-01T05:32:39.111Z, REQUIRES from-change-timestamp)
offset – Retrieves matching records after an offset value (e.g. offset=2)
limit – Retrieves a number of records per page specified by the value (e.g. limit=10)
driver.system – Retrieves matching records based on Driver type, depending on the boolean value specified. (e.g. driver.system=true, false by default) 
   If true, only events from unidentifiedDriver are retrieved. 
   If false, only events from actual drivers are retrieved. 
   Wild-carding using driver.system=* or driver.system=true,false will retrieve events from all Drivers
driver-edit – Retrieves matching records that have been edited or not, depending on the boolean value specified. (e.g driver-edit=true will return events that are manually edited)

can-adl-hours-work-shift-start – Start time date range for filter for canadian additional hours work shift start time.
to-adl-hours-work-shift-start – End time date range for filter for canadian additional hours work shift start time.
SORTING: sort=id – Sort records by their id field in ascending order (DEFAULT)
sort=-id – Sort records by their id field in descending order
sort=uuid – Sort records by their uuid field in ascending order
sort=-uuid – Sort records by their uuid field in descending order
sort=first-name – Sort records by the firstName field of the user in ascending order
sort=-first-name – Sort records by their firstName field of the user in descending order
sort=last-name – Sort records by the lastName field of the user in ascending order
sort=-last-name – Sort records by their lastName field of the user in descending order
sort=suffix – Sort records by the suffix field of the user in ascending order
sort=-suffix – Sort records by their suffix field of the user in descending order
sort=event-time – Sort records by their eventTime field in ascending order
sort=-event-time – Sort records by their eventTime field in descending order
sort=last-changed-date– Sort records by their last change date field in ascending order
sort=-last-changed-date– Sort records by their last change date field in descending order
QUERY STRING EXAMPLES: Get the Driver History record with the specified id: api/v2/driverHistories/5008246
Get all Driver History records for the specified User: ?user-id=1250941
Get two Driver History records of the current Account with an offset of 1 : ?offset=1&limit=2
Get all Driver History records of the current Account sorted by eventTime in ascending order: ?sort=event-time
EXAMPLE RESPONSE: 
[
  {
    "userId": 1253115,
    "uuid": "96e2d49f-abe4-4a65-a808-5d57917f93d9",
    "location": "8561mi N St. John's, 5",
    "driverEdit": false,
    "note": "a note",
    "latitude": 8.47985282,
    "longitude": 124.64723199,
    "odometerKm": 0,
    "editReason": "ELD Device Failure",
    "useCycleReset": true,
    "validBeginTime": "2016-11-10T01:28:15.229Z",
    "vin": "unknown_vin",
    "certificationCount": 0,
    "recordStatus": "Active",
    "engineHours": "PT0S",
    "username": "johndoe@mail.com",
    "distanceLastGpsKm": 0,
    "malfunctionIndicator": false,
    "diagnosticIndicator": false,
    "dataCheck": 52,
    "eventType": "Driving",
    "recordOrigin": "Driver",
    "eventTime": "2016-11-10T01:28:15.229Z",
    "assetId": 1326729,
    "accountId": 1248653,
    "eventSequenceIdentifier": 5,
    "iftaState": "IL",
    "gpsSource": "MOBILE_DEVICE",
    "excludeDrivingEndTimestamp": "2016-11-10T01:29:15.229Z",
    "regulationMode": "AOBRD",
    "odometerSource": "ECU",
    "speedKph": 0,
    "id": 5008246,
    "lastChangedDate": "2016-11-10T01:28:15.229Z"
  }
]

Update

API PATH: /api/v2/driverHistories
METHOD: PUT
EXAMPLE REQUEST: 
[
  {
    "userId": 1253115,
    "uuid": "96e2d49f-abe4-4a65-a808-5d57917f93d9",
    "location": "8561mi N St. John's, 5",
    "driverEdit": false,
    "note": "a note",
    "latitude": 8.47985282,
    "longitude": 124.64723199,
    "odometerKm": 0,
    "editReason": "ELD Device Failure",
    "useCycleReset": true,
    "validBeginTime": "2016-11-10T01:28:15.229Z",
    "vin": "unknown_vin",
    "certificationCount": 0,
    "recordStatus": "Active",
    "engineHours": "PT0S",
    "username": "johndoe@mail.com",
    "distanceLastGpsKm": 0,
    "malfunctionIndicator": false,
    "diagnosticIndicator": false,
    "dataCheck": 52,
    "eventType": "Driving",
    "recordOrigin": "Driver",
    "eventTime": "2016-11-10T01:28:15.229Z",
    "assetId": 1326729,
    "eventSequenceIdentifier": 5,
    "iftaState": "IL",
    "gpsSource": "MOBILE_DEVICE",
    "excludeDrivingEndTimestamp": "2016-11-10T01:29:15.229Z"
    "regulationMode": "AOBRD", "odometerSource":       
    "ECU", "speedKph": 20, "id": 5008246 
 } 
]
EXAMPLE RESPONSE: 
[
  {
    "userId": 1253115,
    "uuid": "96e2d49f-abe4-4a65-a808-5d57917f93d9",
    "location": "8561mi N St. John's, 5",
    "driverEdit": false,
    "note": "a note",
    "latitude": 8.47985282,
    "longitude": 124.64723199,
    "odometerKm": 0,
    "editReason": "ELD Device Failure",
    "useCycleReset": true,
    "validBeginTime": "2016-11-10T01:28:15.229Z",
    "vin": "unknown_vin",
    "certificationCount": 0,
    "recordStatus": "Active",
    "engineHours": "PT0S",
    "username": "johndoe@mail.com",
    "distanceLastGpsKm": 0,
    "malfunctionIndicator": false,
    "diagnosticIndicator": false,
    "dataCheck": 52,
    "eventType": "Driving",
    "recordOrigin": "Driver",
    "eventTime": "2016-11-10T01:28:15.229Z",
    "assetId": 1326729,
    "eventSequenceIdentifier": 5,
    "iftaState": "IL",
    "gpsSource": "MOBILE_DEVICE",
    "excludeDrivingEndTimestamp": "2016-11-10T01:29:15.229Z",
    "regulationMode": "AOBRD", 
    "odometerSource": "ECU", 
    "speedKph": 20, 
    "accountId": 1248653, "id": 5008246,
    "lastChangedDate": "2016-11-10T01:28:15.229Z" 
 } 
]

Vehicles Driven

API PATH: /api/v2/driverHistories/meta/vehiclesDriven
METHOD: GET
PARAMETERS: user-id – Retrieves the list of ids of Vehicles that have been driven by the specific User (e.g. user-id=496650)
EXAMPLE RESPONSE: 
{
  "Vehicles Driven": [
    1460902,
    1460903,
    1460921
  ]
}

Get Unidentified Driving Events

API PATH: /api/v2/driverHistories/meta/unidentifiedDrivingEvents
METHOD: POST
PARAMETERS:
asset-id – The id of the asset to be filtered in the unidentified driving events.

home-terminal-id –  The id of the terminal to be filtered in the unidentified driving events.
from-event-time – Retrieves matching records that occurred on or after the specified date (e.g. from-event-time=2016-07-05T03:03:10.147Z, all dates by default)
to-event-time – Retrieves matching records that occurred on or before the specified date (e.g. to-event-time=2016-07-05T03:03:10.147Z, all dates by default)
event-type – This paramater is used to filter the unidentified driver by event type.
offset – The offset for the response of the unidentified driver
limit – The limit in which how many data are to be returned
record-status – To filter the unidentified driver’s response by its record status.
record-origin – To filter the unidentified driver’s response by its record origin.
is-classified – If is classified is true: should get unldentified driving events which ‘Note’ is NOT equal to ‘Automatic Transition’ and NOT ‘Null’ and NOT empty.
EXAMPLE RESPONSE: 
{
 "userId": 1414887,
 "uuid": "49ca054d-eb30-44e6-9877-672c247d62c9",
 "location": "2mi NW North Las Vegas, NV",
 "driverEdit": false,
 "note": "Automatic Transition",
 "latitude": 36.2175706931051,
 "longitude": -115.142155519392,
 "odometerKm": 504326.685,
 "editReason": "",
 "useCycleReset": true,
 "validBeginTime": "2018-11-11T01:58:55.887Z",
 "validEndTime": "2018-12-12T23:32:06.822Z",
 "vin": "5VCACLSF8EH217029",
 "certificationCount": 0,
 "recordStatus": "InactiveChanged",
 "engineHours": "PT64595520S",
 "username": "rhodegr@repsrv.com",
 "distanceLastGpsKm": 0.015000000013969839,
 "malfunctionIndicator": false,
 "diagnosticIndicator": true,
 "dataCheck": 67,
 "eventType": "Driving",
 "recordOrigin": "Auto",
 "eventTime": "2018-11-11T01:58:55.849Z",
 "assetId": 1581651,
 "state": "NV",
 "autoEventEndTimestamp": "2018-11-11T05:44:01.501Z",
 "gpsSource": "MOBILE_DEVICE",
 "regulationMode": "ELD",
 "odometerSource": "ECU",
 "speedKph": 15.588,
 "accountId": 1255445,
 "id": 178007371,
 "iftaState": "NV",
 "editReasonCode": "",
 "lastChangedDate": "2018-12-12T23:32:07.083Z"
}

API error calls

ERROR MESSAGE POSSIBLE CAUSES
Cannot find requested driver history. (id = <id>) PUT error because driver history with that id does not exist
Cannot find requested user. (id = <id>) POST or PUT because user id for the userId field does not exist in account
Cannot find request asset with id = (id = <id>) POST or PUT because asset id for the assetId field does not exist in account
Cannot edit a driver history that is already edited or deleted. PUT error because driver history is already edited/deleted
Cannot edit a driver history that is not active. PUT error because only active driver history can be edited
Cannot find requested driver history. (id = <id>) PUT error because driver history id does not exist
DELETE is not supported. DELETE error because driver history does not support deleting of records