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
visibilitySetIds Array  Yes List of Visibility Set IDs associated with the User

Create

Read

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

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