Programming Guide to the Hours of Service Platform

Users

A User refers to a member of an Account and has related information within that account. As the name suggests, a User is any person that uses our services. Each User has its own email and password for logging in and his/her accessible services are dependent on the User Roles he/she has in the system.

Note: Accounts with HOS should only use /api/v2/drivers to create/edit/delete Drivers.

Fields

Tag Data Type Required Description
accountId Long No The id of the Account that owns this record.
active Boolean No Indicates if the User is currently active or not
alias Character (255) No  An optional identifier for the User within an Account. This is not shown if the value is null.
authorizedTerminalIds Array No  A list of ids of the Terminals that the User can manage. If the User does not have the Permission PERM_VIEW_ALL_TERMINALS then the Terminals API will only return information for these Terminals.
deactivatedDate Text No  Timestamp when the User was deactivated. This field is not shown for active Users
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
deletedAt Text No  Indicates the date and time when the User was soft-deleted.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z). This is not returned for Users that have not been soft-deleted.
email Character (254) Yes  Email address that uniquely identifies User within the system
enabledFeatures Array No Indicates the features enabled for the User. Can contain any of the following as long as the Account also has them enabled:

  • ELD
  • DVIR
  • WORK_ORDERS
eulaAcceptedDate Text No  Timestamp when the User accepted Hours of Service End User License Agreement
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
firstName Character (255) No  The first name of User
homeTerminalId Long Yes Id of the Terminal where the User is assigned
id Auto-incremented Long Auto  Unique Identifier
isVerified Boolean No  Indicates if the User is verified 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  The last name of the User
password Character (255) Yes  The initial password for User
permissions Array Auto  Contains a list of all the Permissions the User currently has.
subsetId Long No Only for Users that are Drivers. Indicates the Subset of the Terminal where the User is assigned.
suffix Character (25) No  Suffix of the User’s name.
userRoleIds Array Yes  List of User Role IDs the User currently has
UUID Long No  Retrieves matching records with the specified UUID
visibilitySetIds Array  Yes List of Visibility Set IDs associated with the User

Create

API PATH: /api/v2/users
METHOD: POST
EXAMPLE REQUEST: 
[
  {
    "firstName":"John",
    "lastName":"Doe",
    "suffix":"Jr",
    "email":"johndoe@mail.com",
    "password":"123",
    "isVerified":true,
    "userRoleIds": [
      1253415
    ],
    "visibilitySetIds": [
      2161
    ],
    "authorizedTerminalIds":[
      417
    ],
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ]
  }
]
EXAMPLE RESPONSE: 
[
  {
    "firstName": "John",
    "lastName": "Doe",
    "suffix": "Jr",
    "email": "johndoe@mail.com",
    "isVerified":true,
    "eulaAcceptedDate": "2018-06-11T12:00:00.000Z",
    "userRoleIds": [
      1253415
    ],
    "permissions": [
      {
        "name": "PERM_VIEW_PORTAL_UNIDENTIFIED_DRIVING_EVENTS_TAB",
        "category": "Unidentified Driving Events",
        "system": false,
        "id": 17
      },
      {
        "name": "PERM_VIEW_PORTAL_VIOLATIONS_TAB",
        "category": "Violations",
        "system": false,
        "id": 16
      },
      {
        "name": "PERM_VIEW_PORTAL_DVIR_HISTORY_TAB",
        "category": "DVIR History",
        "system": false,
        "id": 19
      },
      {
        "name": "PERM_VIEW_PORTAL_REPORTS_TAB",
        "category": "Reports",
        "system": false,
        "id": 18
      },
      {
        "name": "PERM_IS_ACCOUNT_ADMIN",
        "category": "Users",
        "system": false,
        "id": 4
      },
      {
        "name": "PERM_IS_FLEET_MANAGER",
        "category": "Users",
        "system": false,
        "id": 5
      },
      {
        "name": "PERM_IS_USER_ADMIN",
        "category": "Users",
        "system": false,
        "id": 6
      },
      {
        "name": "PERM_IS_ASSET_ADMIN",
        "category": "Users",
        "system": false,
        "id": 7
      },
      {
        "name": "PERM_IS_ELEVATED_USER",
        "category": "Users",
        "system": false,
        "id": 8
      },
      {
        "name": "PERM_VIEW_ALL_TERMINALS",
        "category": "Terminals",
        "system": false,
        "id": 11
      },
      {
        "name": "PERM_EDIT_USER_PASSWORDS",
        "category": "User Admin",
        "system": false,
        "id": 12
      },
      {
        "name": "PERM_VIEW_PORTAL_DRIVERS_TAB",
        "category": "Drivers",
        "system": false,
        "id": 13
      },
      {
        "name": "PERM_VIEW_PORTAL_DRIVER_LOGS_TAB",
        "category": "Driver Logs",
        "system": false,
        "id": 14
      },
      {
        "name": "PERM_EDIT_PORTAL_DRIVER_LOGS_TAB",
        "category": "Driver Logs",
        "system": false,
        "id": 15
      }
    ],
    "visibilitySetIds": [
      2161
    ],
    "active": true,
    "authorizedTerminalIds": [
      417
    ],
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ],
    "accountId": 1248806,
    "id": 1253458,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Read

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

first-name – Retrieves matching records with the firstName specified (e.g. first-name=John, all first names by default)
driver – Retrieves matching records based on whether a User is a Driver or a plain User (e.g. driver=true, false by default)
system – Retrieves matching records based on User 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 Users are retrieved.
   Wild-carding using system=* or system=true,false will retrieve all Users
search – Retrieves matching records whose full name or email matches the parameter specified (e.g. search=John Doe Jr., all Users by default)
from-change-timestamp – Retrieves matching records that were changed after the specified timestamp (e.g. from-change-timestamp=2018-06-11T12:00:00.000Z)
to-change-timestamp – Retrieves matching records that were changed before the specified timestamp (e.g. to-change-timestamp=2018-06-11T12:00:00.000Z, REQUIRES from-change-timestamp)
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=2018-06-11T12:00:00.000Z&to-deleted-at=2018-06-11T12:00:00.000Z, null by default – returns only non-deleted records)
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)

UUID -Retrieves matching records with the specified UUID

 
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
sort=first-name – Sort records by their name field in ascending order
sort=-first-name – Sort records by their name field in descending order
sort=last-name – Sort records by their name field in ascending order
sort=-last-name – Sort records by their name field in descending order
sort=suffix – Sort records by their name field in ascending order
sort=-suffix – Sort records by their name 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
QUERY STRING EXAMPLE Get the User with the specified id: api/v2/users/1253458
Get two Users of the current Account with an offset of 1 : ?offset=1&limit=2
Get all Users of the current Account sorted by names alphabetically: ?sort=name
EXAMPLE RESPONSE: 
[
  {
    "firstName": "John",
    "lastName": "Doe",
    "suffix": "Jr",
    "email": "johndoe@mail.com",
    "isVerified":true,
    "eulaAcceptedDate": "2018-06-11T12:00:00.000Z",
    "userRoleIds": [
      1253415
    ],
    "permissions": [
      {
        "name": "PERM_VIEW_PORTAL_UNIDENTIFIED_DRIVING_EVENTS_TAB",
        "category": "Unidentified Driving Events",
        "system": false,
        "id": 17
      },
      {
        "name": "PERM_VIEW_PORTAL_VIOLATIONS_TAB",
        "category": "Violations",
        "system": false,
        "id": 16
      },
      {
        "name": "PERM_VIEW_PORTAL_DVIR_HISTORY_TAB",
        "category": "DVIR History",
        "system": false,
        "id": 19
      },
      {
        "name": "PERM_VIEW_PORTAL_REPORTS_TAB",
        "category": "Reports",
        "system": false,
        "id": 18
      },
      {
        "name": "PERM_IS_ACCOUNT_ADMIN",
        "category": "Users",
        "system": false,
        "id": 4
      },
      {
        "name": "PERM_IS_FLEET_MANAGER",
        "category": "Users",
        "system": false,
        "id": 5
      },
      {
        "name": "PERM_IS_USER_ADMIN",
        "category": "Users",
        "system": false,
        "id": 6
      },
      {
        "name": "PERM_IS_ASSET_ADMIN",
        "category": "Users",
        "system": false,
        "id": 7
      },
      {
        "name": "PERM_IS_ELEVATED_USER",
        "category": "Users",
        "system": false,
        "id": 8
      },
      {
        "name": "PERM_VIEW_ALL_TERMINALS",
        "category": "Terminals",
        "system": false,
        "id": 11
      },
      {
        "name": "PERM_EDIT_USER_PASSWORDS",
        "category": "User Admin",
        "system": false,
        "id": 12
      },
      {
        "name": "PERM_VIEW_PORTAL_DRIVERS_TAB",
        "category": "Drivers",
        "system": false,
        "id": 13
      },
      {
        "name": "PERM_VIEW_PORTAL_DRIVER_LOGS_TAB",
        "category": "Driver Logs",
        "system": false,
        "id": 14
      },
      {
        "name": "PERM_EDIT_PORTAL_DRIVER_LOGS_TAB",
        "category": "Driver Logs",
        "system": false,
        "id": 15
      }
    ],
    "visibilitySetIds": [
      2161
    ],
    "active": true,
    "authorizedTerminalIds": [
      417
    ],
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ],
    "accountId": 1248806,
    "id": 1253458,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Read (smaller projection, using GET method)

API PATH: /api/v2/users/meta/names
METHOD: GET
AVAILABLE PARAMETERS: search, name, system, enabled-features, 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,
    "active": true,
    "alias": "Driver-01",
    "id": 1252160
  }
]

Read (smaller projection, using POST method)

API PATH: /api/v2/users/meta/names
METHOD: POST (content-type must be application/x-www-form-urlencoded)
AVAILABLE PARAMETERS: search, name, system, enabled-features, 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,
    "active": true,
    "alias": "Driver-01",
    "id": 1252160
  }
]

Update

API PATH: /api/v2/users
METHOD: PUT
EXAMPLE REQUEST: 
[
  {
    "firstName":"John",
    "lastName":"Doe",
    "suffix":"Jr",
    "email":"johndoe@mail.com",
    "password":"",
    "isVerified":true,
    "userRoleIds": [
      1253415
    ],
    "visibilitySetIds": [
      2161
    ],
    "authorizedTerminalIds": [
      417
    ],
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ],
    "id":1253458
  }
]
EXAMPLE RESPONSE: 
[
  {
    "firstName": "John",
    "lastName": "Doe",
    "suffix": "Jr",
    "email": "johndoe@mail.com",
    "isVerified":true,
    "eulaAcceptedDate": "2018-06-11T12:00:00.000Z",
    "userRoleIds": [
      1253415
    ],
    "permissions": [
      {
        "name": "PERM_VIEW_PORTAL_UNIDENTIFIED_DRIVING_EVENTS_TAB",
        "category": "Unidentified Driving Events",
        "system": false,
        "id": 17
      },
      {
        "name": "PERM_VIEW_PORTAL_VIOLATIONS_TAB",
        "category": "Violations",
        "system": false,
        "id": 16
      },
      {
        "name": "PERM_VIEW_PORTAL_DVIR_HISTORY_TAB",
        "category": "DVIR History",
        "system": false,
        "id": 19
      },
      {
        "name": "PERM_VIEW_PORTAL_REPORTS_TAB",
        "category": "Reports",
        "system": false,
        "id": 18
      },
      {
        "name": "PERM_IS_ACCOUNT_ADMIN",
        "category": "Users",
        "system": false,
        "id": 4
      },
      {
        "name": "PERM_IS_FLEET_MANAGER",
        "category": "Users",
        "system": false,
        "id": 5
      },
      {
        "name": "PERM_IS_USER_ADMIN",
        "category": "Users",
        "system": false,
        "id": 6
      },
      {
        "name": "PERM_IS_ASSET_ADMIN",
        "category": "Users",
        "system": false,
        "id": 7
      },
      {
        "name": "PERM_IS_ELEVATED_USER",
        "category": "Users",
        "system": false,
        "id": 8
      },
      {
        "name": "PERM_VIEW_ALL_TERMINALS",
        "category": "Terminals",
        "system": false,
        "id": 11
      },
      {
        "name": "PERM_EDIT_USER_PASSWORDS",
        "category": "User Admin",
        "system": false,
        "id": 12
      },
      {
        "name": "PERM_VIEW_PORTAL_DRIVERS_TAB",
        "category": "Drivers",
        "system": false,
        "id": 13
      },
      {
        "name": "PERM_VIEW_PORTAL_DRIVER_LOGS_TAB",
        "category": "Driver Logs",
        "system": false,
        "id": 14
      },
      {
        "name": "PERM_EDIT_PORTAL_DRIVER_LOGS_TAB",
        "category": "Driver Logs",
        "system": false,
        "id": 15
      }
    ],
    "visibilitySetIds": [
      2161
    ],
    "active": true,
    "authorizedTerminalIds": [
      417
    ],
    "enabledFeatures": [
      "ELD",
      "DVIR"
    ],
    "accountId": 1248806,
    "id": 1253458,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Delete for the Users API is implemented using a soft-delete. This prevents SQL’s Cascade Delete from deleting any Driving records associated with a deleted User. Eventually, following the motor carrier’s data retention policy, the soft-delete will become a hard-delete.

Delete

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

API error calls

ERROR MESSAGE HTTP STATUS ERROR CODE POSSIBLE CAUSES
The new user to insert should not have an id. 500 1000 POST error because request must not contain an id 
A user with the given email address already exists. 500 3100 POST error because the email address is already used by another User
An email address is required. 500 1000 POST or PUT error because User does not have an email address
<email> is not a valid email address. 500 1000 POST or PUT error because User does not have a valid email address
User does not have sufficient privelege to set isVerified 403 8000 POST or PUT error because setting isVerified requires Permission PERM_IS_USER_ADMIN or higher
Can only create users in your account or your sub accounts. 500 500 POST or PUT error because User is not allowed to create or edit Users on other Accounts 
A user must have at least one visibility set. 500 11000 POST or PUT error because User does not have a Visibility Set
A visibility set was not found with the given name or id. 500 3000 POST or PUT error because the User contained a non-existent Visibility Set
User cannot assign user role: <user role name> 500 20000 POST or PUT error because the current User is not allowed to create or update a User with the given User Role.
UserRole of id <id> does not exist. 500 3000 POST or PUT error because id was not found in the Account
Cannot find Terminal Id <id> 500 1003 POST or PUT error because terminal id was not found in the Account
Users cannot modify their own user roles 500 20000 PUT error because User cannot modify his own User Roles
Id cannot be 0 for updates. 500 4000 PUT error because request requires id
A user with the given id was not found 500 4000 PUT error because User id does not exist
Cannot update system user. 500 1001 PUT error because editing the Unidentified Driver is not allowed
Cannot delete system user. 500 1001 DELETE error because deleting the Unidentified Driver is not allowed
Users cannot delete themselves 500 20000 DELETE error because User is not allowed to Delete himself