Programming Guide to the Hours of Service Platform

Drivers

It is expected that the motor carrier will maintain the master driver’s file and update the Hours of Service system with changes occur. The updates occur using the Drivers endpoint. The updates made on the Drivers endpoint will also reflect on the similar fields that can be found on the Users endpoint, vice versa. Also, any update to the Drivers endpoint will automatically propagate to all of the mobile devices using Android’s syncing process. The Drivers API also provides a meta endpoint that executes faster since it has a smaller projection (only returns specific fields) than the normal GET method.

Fields

The Driver record contains the Driver’s personal information, Terminal, Region. his CDL information and his Driving Cycle and privileges.  The Drivers API is actually based on the Users API, but with User Preferences returned alongside it.

Tag Data Type Required Description
active Boolean No Indicates if the Driver is currently active or not
alias Character (255) No  An optional identifier for the Driver within an Account. This is not shown if the value is null.
authorizedTerminalIds Array No A list of ids of the Terminals that the Driver can manage. If the Driver does not have the Permission PERM_VIEW_ALL_TERMINALS then the Terminals API will only return information for these Terminals.
aobrdSpeedThresholdEnabled Boolean No Indicates if the Driver’s AOBRD Speed Threshold is enabled in the app.
canAddTrailer Boolean No Indicates if the Driver is allowed to add Assets of type Trailer in the app.
canAddVehicle Boolean No Indicates if the Driver is allowed to add Assets of type Vehicle in the app.
canDeleteTrailer Boolean No Indicates if the Driver is allowed to delete Assets of type Trailer in the app.
canDeleteVehicle Boolean No Indicates if the Driver is allowed to delete Assets of type Vehicle in the app. 
canEditTrailer Boolean No Indicates if the Driver is allowed to edit Assets of type Trailer in the app.
canEditVehicle Boolean No Indicates if the Driver is allowed to edit Assets of type Vehicle in the app.
cargo Text No

Type of Cargo carried. Can either be:

  • PROPERTY
  • PASSENGER
cargoChangeAllowed Boolean No

Indicates if the Driver is allowed to change cargo in the app.
carrierId Long No

The id of the Carrier this driver belongs to.
cdlIssuingState Text Yes 

Commercial Driver’s License Issuing State. 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
cdlNumber Text Yes  Commercial Driver’s License Number (1-20 alphanumeric characters)
cycleChangeAllowed Boolean No Indicates if the Driver is allowed to change cycle in the app.
cycleCa Text Yes 

This indicates the type of Canada driving cycle associated with the record when Canada is region is selected. This can either be one of the following:

  • Can70hr7daysSouth
  • Can120hr14daysSouth
  • Can80hr7daysNorth
  • Can120hr14daysNorth
  • Alberta
cycleUsa Text   Yes 

This indicates the type of USA driving cycle associated with the record when USA region is selected. Can either be one of the following:

  • US60hr7days
  • US70hr8days
  • Alabama60hr7days
  • Alabama70hr8days
  • Alaska70hr7days
  • Alaska80hr8days
  • California80hr8days
  • Florida70hr7days
  • Florida80hr8days
  • Illinois60hr7days
  • Illinois70hr8days
  • Maryland70hr7days
  • Maryland80hr8days
  • Massachusetts60hr7days
  • Massachusetts70hr8days
  • Minnesota60hr7days
  • Minnesota70hr8days
  • Michigan60hr7days
  • Michigan70hr8days
  • NewHampshire60hr7days
  • NewHampshire70hr8days
  • NewYork60hr7days
  • NewYork70hr8days
  • NorthCarolina70hr7days
  • NorthCarolina80hr8days
  • NorthDakota70hr7days
  • Pennsylvania60hr7days
  • Pennsylvania70hr8days
  • SouthCarolina70hr7days
  • SouthCarolina80hr8days
  • Tennessee60hr7days
  • Tennessee70hr8days
  • Texas70Hr7days
  • Vermont60hr7days
  • Vermont70hr8days
  • Virginia70hr7days
  • Virginia80hr8days
  • Wisconsin70hr7days
  • Wisconsin80hr8days
cycleMex Text Yes
  • Mexico
deactivatedDate Text No  Timestamp when the Driver was deactivated. This field is not shown for active Drivers.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
driverEditingEnabled Boolean No Defaults to true. All Drivers are allowed to edit their logs.
driverPortalClockAllowed Boolean No Indicates if the Driver is allowed to Clock In/Clock Out from the app
email Character (254) Yes  Email address that uniquely identifies Driver within the system
enabledFeatures Array Yes Indicates the features enabled for this Driver. Can contain any of the following as long as the Account also has them enabled:

  • ELD
  • DVIR
  • WORK_ORDERS
exemptAnnotation Text No  Annotation if the Driver is an exempt Driver
exemptDriver Boolean No  Indicates if the Driver is an exempt Driver or not
firstName Character (255) No  First Name of the Driver
homeTerminalId Long No  Id of the Terminal where the Driver is assigned 
id Auto-incremented Long Auto  Unique identifier for the Driver
isAssetAdmin Boolean No  Indicates if the Driver has an Asset Admin role or not.
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)
lastName Character (255) No  Last Name of the Driver
manageEquipment Boolean No  Indicates if the Driver can manage Equipment. Cannot be used in POST and PUT, only in GET.
offSbPairingMode Character (255) No Indicates the Sleeper Berth Pairing Mode for the Driver
password Character (255) Yes  Initial password for Driver
pcMaxDistanceUSA Integer No Indicates the maximum distance of USA Personal Conveyance for the Driver
recipient Text No  To whom the reports of the Driver will be emailed
region Text Yes 

Information for the region of the Driver.

Can either be “USA“ or “Canada“
showPersonalConveyance Boolean Yes  Indicates if the Driver is allowed Personal Conveyance or not
showYardMoves Boolean Yes  Indicates if the Driver is allowed Yard Moves or not
startTimeOfDay Text Yes  Information for the Start Time of Day of the Driver.
Note: Format must be in (HH:MM:SS)
subsetId Long No Indicates the Subset of the Terminal where the Driver is assigned
suffix Character (25) No  Suffix for the Driver’s name
system Boolean No  Indicates if the Driver is of type system (unidentified driver) or is an authenticated Driver.

Read

API PATH: /api/v2/drivers
METHOD: GET
PARAMETERS:

alias – Retrieves matching records with the specified alias (e.g. alias=Driver-01)
active – Retrieves matching records depending on the boolean value specified. (e.g. active=true)
  If true, only active Drivers is retrieved.
  If false, only inactive Drivers is retrieved.
  If parameter is not included or null, all Drivers are retrieved.
first-name – Retrieves matching records with the specified first name (e.g. first-name=John)
home-terminal-id – Retrieves matching records whose homeTerminalId matches the specified parameter (e.g. home-terminal-id=110, Drivers from all terminals by default)
subset-id – Retrieves matching records whose subsetId matches the specified parameter (e.g. subset-id=940, returns drivers from all subsets by default)
deleted-at – Retrieves matching records that were soft-deleted if set to true. Setting to * will return all records. (e.g. deleted-at=true, false by default – returns only non-deleted records)
from-deleted-at and to-deleted-at – Retrieves matching records that were deleted on or in between the specified timestamps. (e.g. from-deleted-at=2017-05-19T06:51:45.438Z&to-deleted-at=2017-05-19T06:51:45.438Z, null by default – returns only non-deleted records)
system – Retrieves matching records based on Driver type, depending on the boolean value specified. (e.g. system=true, false by default) 
   If true, only the unidentifiedDriver Account is retrieved. 
   If false, only actual Drivers are retrieved. 
   Wild-carding using system=* or system=true,false will retrieve all Drivers 
search – Retrieves matching records whose full name or email matches the parameter specified (e.g. search=John Doe Jr., all Drivers by default)
from-change-timestamp – Retrieves matching records that were changed after the specified timestamp (e.g. from-change-timestamp=2016-07-01T07:44:03.542Z)
offset – Retrieves matching records after an offset value (e.g. offset=2, zero offset by default)
limit – Retrieves a number of records per page specified by the value (e.g. limit=10, all records by default)
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=email – Sort records by their email field in ascending order
sort=-email – Sort records by their email 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
sort=terminal-name – Sort records by their terminal name in ascending order
sort=-terminal-name – Sort records by their terminal name in descending order
QUERY STRING EXAMPLE: Get the Driver with the specified id: api/v2/drivers/1252160
Get all Drivers with a firstName value of “John” : ?first-name=John
Get two Drivers of the current Account with an offset of 1 : ?offset=1&limit=2
Get all Drivers of the current Account sorted by email addresses alphabetically: ?sort=email
EXAMPLE RESPONSE: 
[
  {
    "active": true,
    "alias": "Driver-01",
    "cargo": "PROPERTY",
    "carrierId": 1,
    "cdlIssuingState": "AR",
    "cdlNumber": "CDL12345",
    "cycleCa": "Can70hr7daysSouth",
    "cycleUsa": "US70hr8days",
    "cycleMex": "Mexico",
    "email": "johndoe@mail.com",
    "exemptAnnotation": null,
    "exemptDriver": false,
    "firstName": "John",
    "homeTerminalId": 110,
    "subsetId": 111,
    "isAssetAdmin": true,
    "lastName": "Doe",
    "manageEquipment": true,
    "recipient": "",
    "region": "USA",
    "showPersonalConveyance": true,
    "showYardMoves": true,
    "startTimeOfDay": "00:00:00.000",
    "subsetId": 940,
    "suffix": "Jr.",
    "system":false,
    "canAddVehicle": true,
    "canEditVehicle": true,
    "canDeleteVehicle": false,
    "canAddTrailer": true,
    "canEditTrailer": true,
    "canDeleteTrailer": false,
    "aobrdSpeedThresholdEnabled": false,
    "cycleChangeAllowed": true,
    "carrierId": 1,
    "driverEditingEnabled": true,
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ],
    "offSbPairingMode": "PAIRING_DISABLED",
    "cargoChangeAllowed": false,
    "pcMaxDistanceUSA": 0,
    "driverPortalClockAllowed": false,
    "id": 1252160,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]
   

Read (smaller projection, using GET method)

API PATH: /api/v2/drivers/meta/names
METHOD: GET
AVAILABLE PARAMETERS:

search, name, active, system, offset, limit
AVAILABLE SORTING id, -id, email, -email, terminal.name, -terminal.name
EXAMPLE RESPONSE: 
[
  {
    "firstName": "John",
    "lastName": "Doe",
    "suffix": "Jr.",
    "email": "johndoe@mail.com",
    "homeTerminalId": 110,
    "subsetId": 940,
    "region": "USA",
    "cycleUsa": "US70hr8days",
    "cycleCa": "Can70hr7daysSouth",
    "cycleMex": "Mexico",
    "active": true,
    "alias": "Driver-01",
    "id": 1252160
  }
]

Read (smaller projection, using POST method)

API PATH: /api/v2/drivers/meta/names
METHOD: POST (content-type must be application/x-www-form-urlencoded)
AVAILABLE PARAMETERS:

search, name, active, system, offset, limit
AVAILABLE SORTING id, -id, email, -email, terminal.name, -terminal.name
EXAMPLE REQUEST: 
{"ids": "1252160+1252161"}
EXAMPLE RESPONSE: 
[
  {
    "firstName": "John",
    "lastName": "Doe",
    "suffix": "Jr.",
    "email": "johndoe@mail.com",
    "homeTerminalId": 110,
    "subsetId": 940,
    "region": "USA",
    "cycleUsa": "US70hr8days",
    "cycleCa": "Can70hr7daysSouth",
    "cycleMex": "Mexico",
    "active": true,
    "alias": "Driver-01",
    "id": 1252160
  }
]

Create

API PATH: /api/v2/drivers
METHOD: POST
EXAMPLE REQUEST: 
[
  {
    "active": true,
    "alias": "Driver-01",
    "cargo": "PROPERTY",
    "carrierId": 1,
    "cdlIssuingState": "AR",
    "cdlNumber": "CDL12345",
    "cycleCa": "Can70hr7daysSouth",
    "cycleUsa": "US70hr8days",
    "cycleMex": "Mexico",
    "email": "johndoe@mail.com",
    "exemptAnnotation": null,
    "exemptDriver": false,
    "firstName": "John",
    "homeTerminalId": 110,
    "subsetId": 111,
    "isAssetAdmin": true,
    "lastName": "Doe",
    "manageEquipment": true,
    "recipient": "",
    "region": "USA",
    "showPersonalConveyance": true,
    "showYardMoves": true,
    "startTimeOfDay": "00:00:00.000",
    "subsetId": 940,
    "suffix": "Jr.",
    "system":false,
    "canAddVehicle": true,
    "canEditVehicle": true,
    "canDeleteVehicle": false,
    "canAddTrailer": true,
    "canEditTrailer": true,
    "canDeleteTrailer": false,
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ]
  }
]
EXAMPLE RESPONSE: 
[
  {
    "active": true,
    "alias": "Driver-01",
    "cargo": "PROPERTY",
    "carrierId": 1,
    "cdlIssuingState": "AR",
    "cdlNumber": "CDL12345",
    "cycleCa": "Can70hr7daysSouth",
    "cycleUsa": "US70hr8days",
    "cycleMex": "Mexico",
    "email": "johndoe@mail.com",
    "exemptAnnotation": null,
    "exemptDriver": false,
    "firstName": "John",
    "homeTerminalId": 110,
    "subsetId": 111,
    "isAssetAdmin": true,
    "lastName": "Doe",
    "manageEquipment": true,
    "recipient": "",
    "region": "USA",
    "showPersonalConveyance": true,
    "showYardMoves": true,
    "startTimeOfDay": "00:00:00.000",
    "subsetId": 940,
    "suffix": "Jr.",
    "system":false,
    "canAddVehicle": true,
    "canEditVehicle": true,
    "canDeleteVehicle": false,
    "canAddTrailer": true,
    "canEditTrailer": true,
    "canDeleteTrailer": false,
    "aobrdSpeedThresholdEnabled": false,
    "cycleChangeAllowed": true,
    "carrierId": 1,
    "driverEditingEnabled": true,
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ],
    "offSbPairingMode": "PAIRING_DISABLED",
    "cargoChangeAllowed": false,
    "pcMaxDistanceUSA": 0,
    "driverPortalClockAllowed": false,
    "id": 1252160,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Update

API PATH: /api/v2/drivers
METHOD: PUT
EXAMPLE REQUEST: 
[
  {
    "active": true,
    "alias": "Driver-01",
    "cargo": "PROPERTY",
    "carrierId": 1,
    "cdlIssuingState": "AR",
    "cdlNumber": "CDL12345",
    "cycleCa": "Can70hr7daysSouth",
    "cycleUsa": "US70hr8days",
    "cycleMex": "Mexico",
    "email": "johndoe@mail.com",
    "exemptAnnotation": null,
    "exemptDriver": false,
    "firstName": "John",
    "homeTerminalId": 110,
    "subsetId": 111,
    "isAssetAdmin": true,
    "lastName": "Doe",
    "manageEquipment": true,
    "recipient": "",
    "region": "USA",
    "showPersonalConveyance": true,
    "showYardMoves": true,
    "startTimeOfDay": "00:00:00.000",
    "subsetId": 940,
    "suffix": "Jr.",
    "system":false,
    "canAddVehicle": true,
    "canEditVehicle": true,
    "canDeleteVehicle": false,
    "canAddTrailer": true,
    "canEditTrailer": true,
    "canDeleteTrailer": false,
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ],
    "id": 1252160
  }
]
EXAMPLE RESPONSE: 
[
  {
    "active": true,
    "alias": "Driver-01",
    "cargo": "PROPERTY",
    "carrierId": 1,
    "cdlIssuingState": "AR",
    "cdlNumber": "CDL12345",
    "cycleCa": "Can70hr7daysSouth",
    "cycleUsa": "US70hr8days",
    "cycleMex": "Mexico",
    "email": "johndoe@mail.com",
    "exemptAnnotation": null,
    "exemptDriver": false,
    "firstName": "John",
    "homeTerminalId": 110,
    "subsetId": 111,
    "isAssetAdmin": true,
    "lastName": "Doe",
    "manageEquipment": true,
    "recipient": "",
    "region": "USA",
    "showPersonalConveyance": true,
    "showYardMoves": true,
    "startTimeOfDay": "00:00:00.000",
    "subsetId": 940,
    "suffix": "Jr.",
    "system":false,
    "canAddVehicle": true,
    "canEditVehicle": true,
    "canDeleteVehicle": false,
    "canAddTrailer": true,
    "canEditTrailer": true,
    "canDeleteTrailer": false,
    "aobrdSpeedThresholdEnabled": false,
    "cycleChangeAllowed": true,
    "carrierId": 1,
    "driverEditingEnabled": true,
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ],
    "offSbPairingMode": "PAIRING_DISABLED",
    "cargoChangeAllowed": false,
    "pcMaxDistanceUSA": 0,
    "driverPortalClockAllowed": false,
    "id": 1252160,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Delete

API PATH: /api/v2/drivers/<id>
METHOD: DELETE
REQUIRED FIELDS: id

Delete for the Drivers API is implemented using a soft-delete.  This prevents SQL’s Cascade Delete from deleting any driving records associated with a deleted Driver. The soft-deleted record remains in the database. Eventually, following the motor carrier’s data retention policy, the soft-delete will become a hard-delete.

API error calls

ERROR MESSAGE HTTP STATUS ERROR CODE POSSIBLE CAUSES
Entities should not contain an Id when creating. 500 11000 POST error because request must not contain an id 
Driver with email <email> already exists 500 1001 POST error because of email address is already used by a user in the system.
No password set for this driver 500 7000 POST error because there is no password in the request
CDL Number is already associated with another driver. 500 1004 POST or PUT error because CDL number is already used by a user in the system.
A ROLE_DRIVER must have a HOS_CDL_NUMBER 500 1005 POST or PUT error because there is no cdlIssuingNumber in the request.
A ROLE_DRIVER must have a HOS_CDL_ISSUING_STATE 500 1005 POST or PUT error because there is no cdlIssuingState in the request.
Unable to save record 500 500 POST or PUT error because required fields are missing or incorrect
Driver with ID <id> does not exist. 500 4000 PUT error because id doesn’t exist in the account.
Cannot edit system user 500 1001 PUT method is not allowed for the Unidentified Driver
Cannot delete system user 500 1001 DELETE method is not allowed on the Unidentified Driver 
Access Denied. User is not authorized for this request. 403 8000 POST, PUT and DELETE methods require permission of PERM_EDIT_DRIVERS
Error while handling request 500 500 Generic error message. Something is wrong with the request