Programming Guide to the Hours of Service Platform

Assets

Assets refers to the collection of Vehicles and Trailers owned by an Account. An Asset is paired with a given ELD device capable of periodically reporting back its position and possibly other characteristics of the vehicle. Assets can be associated with Driver Histories, Asset Statuses, etc. containing information that the device and the HOS application has reported back to the Hours of Service servers.

Fields

Tag Data Type Required Description
accountId Long No The id of the Account that owns this record.
assetType Character (255) Yes Indicates the type of this Asset. Can either be one of the following:

  • Vehicle
  • Trailer
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 asset 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 Assets that have not been soft-deleted.
eldConnectionType * Character (255)  No The connection type of the device paired with this Asset. Allowed values:

  • bluetooth
  • wifi_direct_push_button_mode
  • wifi_direct_pin_mode
  • WiFi
eldConfigureWhenConnected * Character (255)  No Indicates whether the Asset is going to be configured when connected to the device.
eldDevice * Character (255)  No  The device type paired with this Asset.
eldDeviceDescription * Character (255)  No  The description of the device paired with this Asset.
eldDeviceManufacturer * Character (255)  No  The manufacturer of the device paired with this Asset.
eldDeviceName * Character (255)  No  The name of the device paired with this Asset.
eldEsn Long (10 digits) No The ELD ESN for the CalAmp device paired with this Asset.
eldMacAddress * Character (255)  No  The MAC address of the device paired with this Asset.
eldPassword * Character (255)  No  The password of the device paired with this Asset.
eldPin * Character (255)  No  The PIN of the device paired with this Asset.
eldWifiApSsid * Character (255)  No  The WiFi AP SSID of the device paired with this Asset.
eldWifiApPassword * Character (255)  No  The WiFI AP password of the device paired with this Asset.
eldWifiSsid * Character (255)  No  The WiFi SSID of the device paired with this Asset.
externalId Character (255)  No  Optional unique identifier for Asset.
fields Array No  A collection of fields containing information of the device paired with this Asset.
Note: This is a legacy property and will be removed on future releases. Use the properties prefixed with “eld” instead.
firmwareVersion Character (255) No  The firmware version of the device paired to this Asset.
formIds Long  No The id of the default DVIR Form associated with the Asset.
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 Asset 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 Asset.
licensePlateState Text (unlimited) No  The state of the license plate of this Asset. 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 Asset as displayed in the user interface.
odometerOffsetKm Double Precision No  Value of the odometer offset of this Asset in kilometers.
regulationMode Character (255) No  Indicates the regulation mode used by this Asset. Can either be “ELD” or “AOBRD”
vin Character (255) No  The VIN of this Asset. This must be valid VIN.
visibilitySetIds Array No Contains a list of IDs of the Visibility Sets that this Asset is included in.
vbusConnectionRequired boolean true If set to true, driver is required to connect to a VBUS device before he can go driving.

Create

API PATH: /api/v2/assets
METHOD: POST
EXAMPLE REQUEST: 
[ 
  { 
    "assetType": "Vehicle",
    "eldConnectionType": "wifi_direct_pin_mode",
    "eldDevice": "DigiWVA",
    "eldDeviceName": "Dev01",
    "eldEsn": 1234567890,
    "eldMacAddress": "A4:3D:2A:FC:C7:59",
    "eldPassword": "MAZS92A004",
    "eldPin": "1234",
    "eldWifiApSsid": "SSID_1234",
    "eldWifiApPassword": "1234",
    "firmwareVersion": "",
    "formIds": [
      1227
    ],
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 12708,
    "licensePlate": "VEH-X01",
    "licensePlateState": "IL",
    "name": "Truck01",
    "regulationMode": "ELD",
    "odometerOffsetKm": 0.0,
    "vbusConnectionRequired": false,
    "vin": "-5TDZA22C04S100724",
     "visibilitySetIds": [
      13017
    ]
  }
]
EXAMPLE RESPONSE: 
[ 
  { 
    "assetType": "Vehicle",
    "createDate": "2018-02-13T03:29:36.287Z",
    "eldConnectionType": "wifi_direct_pin_mode",
    "eldDevice": "DigiWVA",
    "eldDeviceName": "Dev01",
    "eldEsn": 1234567890,
    "eldMacAddress": "A4:3D:2A:FC:C7:59",
    "eldPassword": "MAZS92A004",
    "eldPin": "1234",
    "eldWifiApSsid": "SSID_1234",
    "eldWifiApPassword": "1234",
    "fields":[ 
      { 
        "name":"__eld_pin",
        "value":"1234"
      },
      { 
        "name":"__eld_password",
        "value":"MAZS92A004"
      },
      { 
        "name":"__eld_wifi_ap_password",
        "value":"1234"
      },
      { 
        "name":"__eld_connection_type",
        "value":"wifi_direct_pin_mode"
      },
      { 
        "name":"__eld_device",
        "value":"DigiWVA"
      },
      { 
        "name":"__eld_mac_address",
        "value":"98:87:76:65:54:A4"
      },
      { 
        "name":"__eld_device_name",
        "value":"Dev01"
      },
      {
        "name":"__eld_wifi_ap_ssid",
        "value":"SSID_1234"
      }
    ],
    "firmwareVersion": "",
    "formIds": [
      1227
    ],
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 12708,
    "licensePlate": "VEH-X01",
    "licensePlateState": "IL",
    "name": "Truck01",
    "regulationMode": "ELD",
    "odometerOffsetKm": 0.0,
    "vin": "-5TDZA22C04S100724",
    "visibilitySetIds": [
      13017
    ],
    "accountId": 1259472,
    "vbusConnectionRequired": false
    "id": 1452357,
    "lastChangedDate": "2018-02-13T03:29:36.287Z"
  }
]

Read

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

name – Retrieves the matching Asset with the specified name (e.g. name=Vehicle X, all names by default) 
asset-type – Retrieves matching Assets that belong to a specific asset type (e.g. asset-type=Vehicle, all types by default)
vin – Retrieves the matching Asset with the specified VIN (e.g. vin=VIN-00000000000002, all VINs by default)
visibility-set-id – Retrieves the matching Assets that belong to the specified Visibility Set (e.g. visibility-set-id=2007, all visibility sets by default)  
license-plate – Retrieves the matching Asset with the specified license plate (e.g. license-plate=LIC-002, all plates by default)
from-deleted-at – Retrieves matching Asset that were deleted after the specified timestamp. Setting to * will return all records. (e.g. from-deleted-at=2016-11-11T06:57:06.629Z, null by default – returns only non-deleted records)
from-change-timestamp – Retrieves matching Assets that were changed after the specified timestamp (e.g. from-change-timestamp=2016-11-11T06:57:06.629Z, all timestamps by default)
to-change-timestamp – Retrieves matching Assets that were changed before the specified timestamp (e.g. to-change-timestamp=2016-11-11T06:57:06.629Z, REQUIRES from-change-timestamp)
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=external-id – Sort records by their externalId field in ascending order
sort=-external-id – Sort records by their externalId 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
sort=last-changed-date– Sort records by their last change date field in ascending order
sort=-last-changed-date– Sort records by their last change date field in descending order
QUERY STRING EXAMPLES:  Get the asset with the specified id: api/v2/assets/1328279
Get all assets of the current account with the type of Trailer : ?asset-type=Trailer
Get two assets of the current account with an offset of 1 : ?offset=1&limit=2
Get all assets of the current account sorted by names alphabetically: ?sort=name
EXAMPLE RESPONSE: 
[ 
  { 
    "assetType": "Vehicle",
    "createDate": "2018-02-13T03:29:36.287Z",
    "eldConnectionType": "wifi_direct_pin_mode",
    "eldDevice": "DigiWVA",
    "eldDeviceName": "Dev01",
    "eldEsn": 1234567890,
    "eldMacAddress": "A4:3D:2A:FC:C7:59",
    "eldPassword": "MAZS92A004",
    "eldPin": "1234",
    "eldWifiApSsid": "SSID_1234",
    "eldWifiApPassword": "1234",
    "fields":[ 
      { 
        "name":"__eld_pin",
        "value":"1234"
      },
      { 
        "name":"__eld_password",
        "value":"MAZS92A004"
      },
      { 
        "name":"__eld_wifi_ap_password",
        "value":"1234"
      },
      { 
        "name":"__eld_connection_type",
        "value":"wifi_direct_pin_mode"
      },
      { 
        "name":"__eld_device",
        "value":"DigiWVA"
      },
      { 
        "name":"__eld_mac_address",
        "value":"98:87:76:65:54:A4"
      },
      { 
        "name":"__eld_device_name",
        "value":"Dev01"
      },
      {
        "name":"__eld_wifi_ap_ssid",
        "value":"SSID_1234"
      }
    ],
    "firmwareVersion": "",
    "formIds": [
      1227
    ],
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 12708,
    "licensePlate": "VEH-X01",
    "licensePlateState": "IL",
    "name": "Truck01",
    "regulationMode": "ELD",
    "odometerOffsetKm": 0.0,
    "vin": "-5TDZA22C04S100724",
    "visibilitySetIds": [
      13017
    ],
    "accountId": 1259472,
    "vbusConnectionRequired":false
    "id": 1452357,
    "lastChangedDate": "2018-02-13T03:29:36.287Z"
  }
]
   

Update

API PATH: /api/v2/assets
METHOD: PUT
EXAMPLE REQUEST: 
[ 
  { 
    "assetType": "Vehicle",
    "eldConnectionType": "wifi_direct_pin_mode",
    "eldDevice": "DigiWVA",
    "eldEsn": 1234567890,
    "eldDeviceName": "Dev01",
    "eldMacAddress": "A4:3D:2A:FC:C7:59",
    "eldPassword": "MAZS92A004",
    "eldPin": "1234",
    "eldWifiApSsid": "SSID_1234",
    "eldWifiApPassword": "1234",
    "firmwareVersion": "",
    "formIds": [
      1227
    ],
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 12708,
    "licensePlate": "VEH-X01",
    "licensePlateState": "IL",
    "name": "Truck01",
    "regulationMode": "AOBRD",
    "odometerOffsetKm": 0.0,
    "vin": "-5TDZA22C04S100724",
    "vbusConnectionRequired": false,
    "visibilitySetIds": [
      13017
    ],
    "id": 1452357
  }
]
EXAMPLE RESPONSE: 
[ 
  { 
    "assetType": "Vehicle",
    "createDate": "2018-02-13T03:29:36.287Z",
    "eldConnectionType": "wifi_direct_pin_mode",
    "eldDevice": "DigiWVA",
    "eldDeviceName": "Dev01",
    "eldEsn": 1234567890,
    "eldMacAddress": "A4:3D:2A:FC:C7:59",
    "eldPassword": "MAZS92A004",
    "eldPin": "1234",
    "eldWifiApSsid": "SSID_1234",
    "eldWifiApPassword": "1234",
    "fields":[ 
      { 
        "name":"__eld_pin",
        "value":"1234"
      },
      { 
        "name":"__eld_password",
        "value":"MAZS92A004"
      },
      { 
        "name":"__eld_wifi_ap_password",
        "value":"1234"
      },
      { 
        "name":"__eld_connection_type",
        "value":"wifi_direct_pin_mode"
      },
      { 
        "name":"__eld_device",
        "value":"DigiWVA"
      },
      { 
        "name":"__eld_mac_address",
        "value":"98:87:76:65:54:A4"
      },
      { 
        "name":"__eld_device_name",
        "value":"Dev01"
      },
      {
        "name":"__eld_wifi_ap_ssid",
        "value":"SSID_1234"
      }
    ],
    "firmwareVersion": "",
    "formIds": [
      1227
    ],
    "gpsSource": "EITHER_DEVICE",
    "homeTerminalId": 12708,
    "licensePlate": "VEH-X01",
    "licensePlateState": "IL",
    "name": "Truck01",
    "regulationMode": "AOBRD",
    "odometerOffsetKm": 0.0,
    "vin": "-5TDZA22C04S100724",
    "visibilitySetIds": [
      13017
    ],
    "accountId": 1259472,
    "id": 1452357,
    "lastChangedDate": "2018-02-13T03:39:36.287Z"
  }
]

Delete

API PATH: /api/v2/assets/<id>
METHOD: DELETE
DESCRIPTION: Supports soft delete. Requires the PERM_EDIT_EQUIPMENT permission for users and drivers. Drivers must also be allowed to delete equipment, based on the “hos.driver.equipment.delete” account property and their “HOS_DELETE_EQUIPMENT” user preference, both must be set to true

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

Vehicle’s eldConnectionProperties

The properties prefixed with “eld” (previously the “fields” property) are the eldConnectionProperties of an Asset. These fields contain the configuration details needed for setting up the devices that the Hours of Service system supports. The details on how to use the fields with regards to the devices are explained fully in the Installation Guides.

API error calls

ERROR MESSAGE POSSIBLE CAUSES
Access Denied. POST, PUT and DELETE methods require a user role of ASSETADMIN or higher
An asset with the given id was not found PUT error because asset id does not exist
Cannot modify a deleted entity. PUT error because a soft-deleted record cannot be updated.
Entity is already deleted. DELETE error because a soft-deleted record cannot be deleted again.