Programming Guide to the Hours of Service Platform

HOS Carrier Properties

The HOS Carrier Properties endpoint handles a collection of Carriers from which admin personnel can assign Drivers to, depending on which Carrier they are working for on that particular day. It should be noted that values saved using this API are saved into the Account Property named “hos.carrier.information” and if the default Carrier is edited, it also updates the “hos.mainoffice.*” Account Properties.

Fields

An individual Carrier is required to have name and a DOT Number, along with a full address divided up into separate fields and a corresponding timezone.

Tag Data Type Required Description
accountId Long No The id of the Account that owns this record.
carrierName Text (max of 120 characters) Yes  The name of the Carrier
carrierDotNumber Integer (max value of 999999999) Yes  The DOT number of the Carrier
city Text (unlimited) Yes  The city where the Carrier is located
country Text (unlimited) Yes  The country where the Carrier is located. Can be:

  • USA
  • Canada
  • Mexico
id Auto-incremented Long Auto  Unique Identifier for the Carrier
isDefault Boolean No  Indicates whether the Carrier is the default Carrier or not. Only one Carrier can be set as default at any given time. Setting this to true for one Carrier will set all other Carriers to false
phoneNumber Character (50) Yes  The phone number of the Carrier
zip Text (unlimited) Yes  The postal code where the Carrier is located
startTimeOfDay Text Yes  The start time of day set for the Carrier
Note: Format must be in (HH:MM:SS)
state Text (must be valid state code) Yes  The state where the Carrier is located. 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, 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
street Text (unlimited) Yes  The street where the Carrier is located
timezone Text (unlimited) Yes 

Timezone where the Carrier is located. Can either be:

  • America/Anchorage
  • America/Phoenix
  • Canada/Atlantic
  • Canada/Newfoundland
  • CST6CDT
  • EST5EDT
  • Pacific/Honolulu
  • MST7MDT
  • America/Indiana/Knox
  • PST8PDT
  • America/Regina

Read

API PATH: /api/v2/hosCarrierProperties
METHOD: GET
EXAMPLE RESPONSE: 
[
  {
    "carrierName": "Carrier 1",
    "carrierDotNumber": 208029,
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "IN",
    "country": "USA",
    "zip": "46405",
    "phoneNumber": "1223334444",
    "timezone": "CST6CDT",
    "startTimeOfDay": "00:00:00",
    "isDefault": true,
    "accountId": 2251360,
    "id": 1
  }
]

Create

API PATH: /api/v2/hosCarrierProperties
METHOD: POST
EXAMPLE REQUEST: 
[
  {
    "carrierName": "Carrier 2",
    "carrierDotNumber": 208029,
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "IN",
    "country": "USA",
    "zip": "46405",
    "phoneNumber": "1223334444",
    "timezone": "CST6CDT",
    "startTimeOfDay": "00:00:00",
    "isDefault": false,
    "accountId": 2251360,
    "id": 2
  }
]
EXAMPLE RESPONSE: 
[
  {
    "carrierName": "Carrier 2",
    "carrierDotNumber": 208029,
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "IN",
    "country": "USA",
    "zip": "46405",
    "phoneNumber": "1223334444",
    "timezone": "CST6CDT",
    "startTimeOfDay": "00:00:00",
    "isDefault": false,
    "accountId": 2251360,
    "id": 2
  }
]

Update

API PATH: /api/v2/hosCarrierProperties
METHOD: PUT
EXAMPLE REQUEST: 
[
  {
    "carrierName": "Carrier 2 edited",
    "carrierDotNumber": 208029,
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "IN",
    "country": "USA",
    "zip": "46405",
    "phoneNumber": "1223334444",
    "timezone": "CST6CDT",
    "startTimeOfDay": "00:00:00",
    "isDefault": true,
    "accountId": 2251360,
    "id": 2
  }
]
EXAMPLE RESPONSE: 
[
  {
    "carrierName": "Carrier 2 edited",
    "carrierDotNumber": 208029,
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "IN",
    "country": "USA",
    "zip": "46405",
    "phoneNumber": "1223334444",
    "timezone": "CST6CDT",
    "startTimeOfDay": "00:00:00",
    "isDefault": true,
    "accountId": 2251360,
    "id": 2
  }
]

Delete

API PATH: /api/v2/hosCarrierProperties/<id>
METHOD: DELETE
REQUIRED FIELDS: id

 

API error calls

ERROR MESSAGE HTTP STATUS ERROR CODE POSSIBLE CAUSES
Default Carrier can not be deleted. 500 11000 Deleting the default carrier is not allowed
There is a problem reading the carrier information account property 500 1000 The Carrier Information Account Property cannot be read properly or is not in a valid JSON format
Error while handling request 500 500 Generic error message. Something is wrong with the request