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)
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
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 No 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

Create OffDuty event

Create Driving event

Read

Update

Vehicles Driven

Get Unidentified Driving Events

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