Alerts – Programming Guide to the Hours of Service Platform

Alerts are used to set up Alert Notifications that will be sent to a predefined list of email addresses and phone numbers, depending on the selected Drivers or Terminals. Violation Warning alerts are sent only once approximately one hour before the Violation occurs while all the other Alerts are sent as they occur given that the device has internet connection. Events that occurred more than 24 hours ago do not send any Alerts.

Fields

Tag	Data Type	Required	Description
accountId	Long	No	The id of the Account that owns this record.
assignBy	Character (20)	Yes	Indicates if the Alert is monitored based on the selected Drivers or based on the Drivers who belong to the selected Terminals. The only values allowed are: DRIVERS TERMINALS
documentSaved	Boolean	Yes	Indicates if the Alert set-up sends Alert Notifications when a Driver Daily Document is saved by a monitored driver.
dvirDefects	Boolean	Yes	Indicates if the Alert set-up sends Alert Notifications when a DVIR with defects is performed by a monitored driver.
dvirFailure	Boolean	Yes	Indicates if the Alert set-up sends Alert Notifications when a DVIR marked as failed is performed by a monitored driver.
emails	Object	No	A comma-separated list of email addresses that will receive Alert Notifications depending on the options set to true.
id	Auto-incremented Long	Auto	Unique Identifier
name	Text (unlimited)	Yes	The name of the Alert set-up.
preTripDvir	Boolean	Yes	Indicates if the Alert set-up sends Alert Notifications when a Vehicle has been driven by a monitored driver without performing a PRE-TRIP DVIR.
sms	Object	No	A comma-separated list of phone numbers that will receive SMS Notifications depending on the options set to true.
terminalIds	Object	Yes *	A comma-separated list of Terminal IDs that will be used in determining which Drivers will send Alert Notifications.
unidentifiedDrivingMode	Boolean	Yes	Indicates if the Alert set-up sends Alert Notifications when any Driver under this Account enters Unidentified Driving mode.
userIds	Object	Yes **	A comma-separated list of User IDs that will be used in determining which Drivers will send Alert Notifications.
violationNotification	Boolean	Yes	Indicates if the Alert set-up sends Alert Notifications when a monitored Driver commits a Driver Violation.
breakViolationWarningThreshold	Duration	PT0S	The amount of time on which the driver will be given a warning for break type violations. If the value of this warning is PT0S (0 seconds) there will be no warning for that driver.
cycleViolationWarningThreshold	Duration	PT0S	The amount of time on which the driver will be given a warning for cycle type violations. If the value of this warning is PT0S (0 seconds) there will be no warning for that driver.
drivingViolationWarningThreshold	Duration	PT0S	The amount of time on which the driver will be given a warning for driving type violations. If the value of this warning is PT0S (0 seconds) there will be no warning for that driver.
shiftViolationWarningThreshold	Duration	PT0S	The amount of time on which the driver will be given a warning for shift type violations. If the value of this warning is PT0S (0 seconds) there will be no warning for that driver.
nextViolationWarningThreshold	Duration	PT0S	The amount of time on which the driver will be given a warning for next violations. If the value of this warning is PT0S (0 seconds) there will be no warning for that driver.

* Required if assignBy is set to TERMINALS and unidentifiedDrivingMode is not set to true

** Required if assignBy is set to DRIVERS and unidentifiedDrivingMode is not set to true

Create

API PATH:	/api/v2/alerts
METHOD:	POST
EXAMPLE REQUEST:	[ { "name": "ALERT BY DRIVERS", "assignBy": "DRIVERS", "breakViolationWarningThreshold": "PT3600S", "cycleViolationWarningThreshold": "PT3600S", "drivingViolationWarningThreshold": "PT0S", "nextViolationWarningThreshold" : "PT3600S", "shiftViolationWarningThreshold" : "PT3600S", "violationNotification": true, "unidentifiedDrivingMode": true, "dvirFailure": true, "preTripDvir": true, "documentSaved": true, "dvirDefects": true, "emails": [ "adminjohn@mail.com", "adminfrank@mail.com" ], "sms": [ "12223334444", "56667778888" ], "userIds": [ 1264360, 1264361 ] } ]
EXAMPLE RESPONSE:	[ { "name": "ALERT BY DRIVERS", "assignBy": "DRIVERS", "breakViolationWarningThreshold": "PT3600S", "cycleViolationWarningThreshold": "PT3600S", "drivingViolationWarningThreshold": "PT0S", "nextViolationWarningThreshold" : "PT3600S", "shiftViolationWarningThreshold" : "PT3600S", "violationWarning": true, "violationNotification": true, "unidentifiedDrivingMode": true, "dvirFailure": true, "preTripDvir": true, "documentSaved": true, "dvirDefects": true, "emails": [ "adminjohn@mail.com", "adminfrank@mail.com" ], "sms": [ "12223334444", "56667778888" ], "userIds": [ 1264360, 1264361 ], "accountId": 1249882, "id": 5 } ]

Read

API PATH:	/api/v2/alerts
METHOD:	GET
PARAMETERS:	name – Retrieves matching records based on the name provided (e.g. name=Violation Alerts, all records by default) assign-by – Retrieves matching records based on the assignBy field (e.g. assign-by=DRIVERS, all records by default) 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=name – Sort records by their name field in ascending order sort=-name – Sort records by their name field in descending order
QUERY STRING EXAMPLE	Get the alert with the specified id: api/v2/alerts/1253423 Get two alerts of the current account with an offset of 1 : ?offset=1&limit=2 Get all alerts of the current account sorted by names alphabetically: ?sort=name
EXAMPLE RESPONSE:	[ { "name": "ALERT BY TERMINALS", "assignBy": "TERMINALS", "violationWarning": true, "violationNotification": true, "unidentifiedDrivingMode": false, "dvirFailure": false, "preTripDvir": true, "documentSaved": true, "dvirDefects": true, "emails": [ "adminjohn@mail.com", "adminfrank@mail.com" ], "sms": [ "12345678901", "98765432109" ], "terminalIds": [ 797, 798 ], "accountId": 1249882, "id": 6 } ]

Update

API PATH:	/api/v2/alerts
METHOD:	PUT
EXAMPLE REQUEST:	[ { "name": "ALERT BY DRIVERS", "assignBy": "DRIVERS", "violationWarning": true, "violationNotification": true, "unidentifiedDrivingMode": false, "dvirFailure": false, "preTripDvir": true, "documentSaved": true, "dvirDefects": true, "emails": [ "adminjohn@mail.com", "adminfrank@mail.com" ], "sms": [ "12223334444", "56667778888" ], "userIds": [ 1264360, 1264361 ], "id": 5 } ]
EXAMPLE RESPONSE:	[ { "name": "ALERT BY DRIVERS", "assignBy": "DRIVERS", "violationWarning": true, "violationNotification": true, "unidentifiedDrivingMode": false, "dvirFailure": false, "preTripDvir": true, "documentSaved": true, "dvirDefects": true, "emails": [ "adminjohn@mail.com", "adminfrank@mail.com" ], "sms": [ "12223334444", "56667778888" ], "userIds": [ 1264360, 1264361 ], "accountId": 1249882, "id": 5 } ]

Delete

API PATH:	/api/v2/alerts/<id>
METHOD:	DELETE

API error calls

ERROR MESSAGE	POSSIBLE CAUSES
Invalid data in assignBy field must be either DRIVERS or TERMINALS.	POST or PUT error because the assignBy field is not equal to “DRIVERS” or “TERMINALS”.
Alert must not contain terminal ids when assignBy is set to DRIVERS	POST or PUT error because the request passed terminal ids but the alert assign by is set to DRIVERS
Alert must contain at least one user id when assignBy is set to DRIVERS	POST or PUT error because the request did not contain user ids and unidentifiedDrivingMode is not set to true
Alert must not contain user ids when assignBy is set to TERMINALS	POST or PUT error because the request passed user ids but the the alert assign by is set to TERMINALS
Alert must contain at least one terminal id when assignBy is set to TERMINALS	POST or PUT error because the request did not contain terminal ids and unidentifiedDrivingMode is not set to true