Programming Guide to the Hours of Service Platform

Equipment

In the Hours of Service platform, Equipment (Vehicles, Trailers) are modeled from Assets. The Equipment API provides simplified interface for Assets API and both may be used to manipulate Assets in the Hours of Service platform. The Equipment 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 Equipment record contains the Equipment’s vehicular information, its name and type, associated DVIR Form, its Terminal, the Visibility Set it belongs to and the ELD properties associated with it.

Tag Data Type Required Description
assetType Character (255) Yes

Indicates the type of this Equipment. Can either be one of the following:

  • Vehicle
  • Trailer
active Boolean No

Indicates if the current equipment is active or inactive.
createDate Text Auto

Auto-generated timestamp of the date and time this record was created.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
deletedAt Text Auto Indicates the date and time when the Equipment 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 Equipment that have not been soft-deleted.
eldConnectionProperties Object No A collection of fields containing information of the device paired with this Equipment.
eldEsn Long (10 digits) No The ELD ESN for the CalAmp device paired with this Equipment.
formId Long No The id of the default DVIR Form associated with the Equipment.
gpsSource Character (255) No Indicates the GPS source used by the Asset when reporting location. Can be any of the following values:

  • MOBILE_DEVICE
  • VBUS_DEVICE
  • EITHER_DEVICE
homeTerminalId Long No The id of the Terminal under which this Equipment belongs to. If not provided in the JSON POST or PUT, automatically assigns the authenticated Driver’s homeTerminalId or the Main Office Terminal if not available
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)
licensePlate Text (unlimited) No The license plate of this Equipment.
licensePlateState Text (unlimited) No The state of the license plate of this Equipment. 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
name Character (20) Yes The name of Equipment as displayed in the user interface.
odometerOffsetKm Double Precision No Value of the odometer offset of this Equipment in kilometers.
regulationMode Character (255) No Indicates the regulation mode used by this Equipment. Can either be “ELD” or “AOBRD”
vin Character (255) No The VIN of this Equipment.
visibilitySetIds Array No Contains a list of IDs of the Visibility Sets that this Equipment is included in.
Note: When there is no Visibility Set saved, the Account’s default Visibility Set is set. Users with PERM_IS_ASSETADMIN only cannot assign Visibility Sets they do not have access to.
vbusConnectionRequired boolean true If set to true, driver is required to be connected to a VBUS device before he can go driving.

Read

API PATH: /api/v2/equipment
METHOD: GET
PARAMETERS: name – Retrieves matching records with the specified name (e.g. name=Truck12, all names by default)
asset-type – Retrieves matching records that belong to a specific asset type (e.g. asset-type=Vehicle, all types by default)
home-terminal-id – Retrieves matching records whose homeTerminalId matches the specified parameter (e.g. home-terminal-id=634, all home terminals by default)
from-deleted-at – Retrieves matching records that were deleted after the specified timestamp. Setting to * will return all records. (e.g. from-deleted-at=2018-06-11T12:00:00.000Z, null by default – returns only non-deleted records)
from-change-timestamp – Retrieves matching records that were changed after the specified timestamp (e.g. from-change-timestamp=2018-06-11T12:00:00.000Z)
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
sort=asset-type – Sort records by their assetType in ascending order
sort=-asset-type – Sort records by their assetType field in descending order
QUERY STRING EXAMPLES: Get the Equipment with the specified id: api/v2/equipment /1323163
Get specific Equipment of the current Account with the name of Vehicle1 : ?name=Vehicle1
Get two Equipment of the current Account with an offset of 1 : ?offset=1&limit=2
Get all Equipment of the current Account sorted by name alphabetically: ?sort=name
EXAMPLE RESPONSE: 
[
  {
    "assetType": "Vehicle",
    "createDate": "2018-06-11T12:00:00.000Z",
    "eldConnectionProperties": {
      "eld_pin": "1234",
      "eld_device": "CalAmpLmu4230BT",
      "eld_connection_type": "bluetooth",
      "eld_device_name": "Name",
      "eld_mac_address": "A4:3D:2A:FC:C7:59"
    },
    "eldEsn": 1234567890,
    "formId": 1224,
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 121,
    "licensePlate": "VEH-X01",
    "licensePlateState": "IL",
    "name": "Vehicle1",
    "regulationMode": "AOBRD",
    "odometerOffsetKm": 0,
    "vin": "-2G4GP5EC3B9205441",
    "visibilitySetIds": [
      1735
    ],
    "id": 1323163,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
    "vbusConnectionRequired": false
  }
]

Read (smaller projection, using GET method)

API PATH: /api/v2/equipment/meta/names
METHOD: GET
AVAILABLE PARAMETERS: search, asset-type, offset, limit
AVAILABLE SORTING: id, -id, name, -name
EXAMPLE RESPONSE: 
[
  {
    "name": "Vehicle1",
    "id": 1323163
  }
]

Read (smaller projection, using POST method)

API PATH: /api/v2/equipment/meta/names
METHOD: POST (content-type must be application/x-www-form-urlencoded)
AVAILABLE PARAMETERS: search, asset-type, offset, limit
AVAILABLE SORTING: id, -id, name, -name
EXAMPLE REQUEST: 
{"ids": "1323163+1323164"}
EXAMPLE RESPONSE: 
[
  {
    "name": "Vehicle1",
    "id": 1323163
  }
]

Create

API PATH: /api/v2/equipment
METHOD: POST
EXAMPLE REQUEST (Vehicle): 
[
  {
    "assetType": "Vehicle",
    "eldConnectionProperties": {
      "eld_pin": "1234",
      "eld_device": "CalAmpLmu4230BT",
      "eld_connection_type": "bluetooth",
      "eld_device_name": "Name",
      "eld_mac_address": "A4:3D:2A:FC:C7:59"
    },
    "eldEsn": 1234567890,
    "formId": 1224,
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 121,
    "licensePlate": "VEH-X01",
    "licensePlateState": "IL",
    "name": "Vehicle1",
    "regulationMode": "AOBRD",
    "odometerOffsetKm": 0,
    "vin": "-2G4GP5EC3B9205441",
    "vbusConnectionRequired": false,
    "visibilitySetIds": [
      1735
    ]
  }
]
EXAMPLE REQUEST (Trailer): 
[
  {
    "assetType": "Trailer",
    "eldConnectionProperties": null,
    "formId": 1225,
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 121,
    "licensePlate": "TRA-001",
    "licensePlateState": "IL",
    "name": "Trailer1",
    "odometerOffsetKm": 0,
    "vbusConnectionRequired": false,
    "visibilitySetIds": [
      1735
    ]
  }
]

Update

API PATH: /api/v2/equipment
METHOD: PUT
REQUIRED FIELDS: assetType, name, id
Note: When fields are not included in PUT, they are saved as their default values (false for boolean types, empty strings for text and character types). When there is no visibility set ids saved, the account’s default visibility set is set. Users with PERM_IS_ASSETADMIN only cannot assign or remove visibility sets they do not have access to.
EXAMPLE REQUEST: 
[
  {
    "assetType": "Vehicle",
    "eldConnectionProperties": {
      "eld_pin": "1234",
      "eld_device": "CalAmpLmu4230BT",
      "eld_connection_type": "bluetooth",
      "eld_device_name": "Name",
      "eld_mac_address": "A4:3D:2A:FC:C7:59"
    },
    "eldEsn": 1234567890,
    "formId": 1224,
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 121,
    "licensePlate": "VEH-X01",
    "licensePlateState": "IL",
    "name": "Vehicle1C",
    "regulationMode": "AOBRD",
    "odometerOffsetKm": 0,
    "vin": "-2G4GP5EC3B9205441",
    "vbusConnectionRequired": false,
    "visibilitySetIds": [
      1735
    ],
    "id": 1323163
  }
]
EXAMPLE RESPONSE: 
[
  {
    "assetType": "Vehicle",
    "createDate": "2018-06-11T12:00:00.000Z",
    "eldConnectionProperties": {
      "eld_pin": "1234",
      "eld_device": "CalAmpLmu4230BT",
      "eld_connection_type": "bluetooth",
      "eld_device_name": "Name",
      "eld_mac_address": "A4:3D:2A:FC:C7:59"
    },
    "eldEsn": 1234567890,
    "formId": 1224,
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 121,
    "licensePlate": "VEH-X01",
    "licensePlateState": "IL",
    "name": "Vehicle1C",
    "regulationMode": "AOBRD",
    "odometerOffsetKm": 0,
    "vin": "-2G4GP5EC3B9205441",
    "vbusConnectionRequired": false,
    "visibilitySetIds": [
      1735
    ],
    "id": 1323163,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]
   

Delete

API PATH: /api/v2/equipment/<id>
METHOD: DELETE
DESCRIPTION: Supports soft delete. Requires the PERM_EDIT_EQUIPMENT permission for Users and Drivers. Drivers can be allowed to delete Equipment if the “hos.driver.equipment.delete” Account Property and their “HOS_DELETE_EQUIPMENT” User Preference are both set to true

Delete for the Equipment API is implemented using a soft-delete. This prevents SQL’s Cascade Delete from deleting any Driving records associated with a deleted piece of Equipment. 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
Equipment with name <name> already exists 500 1001 POST error because Equipment name is already used by an Equipment in the system.
You are not allowed to create an equipment and assign a visibility set you do not have access to. 403 8000 POST error because request contains a Visibility Set that the PERM_IS_ASSETADMIN User does not have access to.
Equipment should have an asset type. 500 7000 POST and PUT methods require the asset type of ‘Vehicle’ or ‘Trailer’
Trailer name cannot be more than 10 characters. 500 1005 POST or PUT error because name of Trailer exceeds 10 characters.
Trailer name can only contain alphanumeric characters, no spaces. 500 1005 POST or PUT error because name of Trailer contains invalid characters.
A visibility set was not found with the given name or id. 500 17000 POST or PUT error because the Equipment contained a non-existent Visibility Set
Asset named <name> already exists. 500 2000 PUT error because Equipment name is already used by an Equipment in the system.
You are not allowed to remove an equipment from a visibility set you do not have access to. 403 8000 PUT error because request attempted to remove a Visibility Set that the PERM_IS_ASSETADMIN User does not have access to.
You are not allowed to update an equipment from a visibility set you do not have access to. 403 8000 PUT error because request attempted to add a Visibility Set that the PERM_IS_ASSETADMIN User does not have access to.
Cannot modify a deleted entity. 500 11000 PUT error because a soft-deleted record cannot be updated.
Access Denied. User is not allowed to delete this record. 403 8000 DELETE error because Driver is not allowed to delete the Equipment
Entity is already deleted. 500 11000 DELETE error because a soft-deleted record cannot be deleted again.
Access Denied. User is not authorized for this request. 403 8000 POST, PUT and DELETE methods require permission of PERM_EDIT_EQUIPMENT
Error while handling request 500 500 Generic error message. Something is wrong with the request