Terminals

The Terminals endpoint contains a list of the locations for the motor carrier’s Terminals.  It is used to filter results on the portal, e.g. to show all Drivers or Equipment assigned under a particular Terminal.  Both the Drivers and Equipment APIs have a foreign key relationship with Terminals API.

Fields

Aside from the name field, the Terminals API also requires the startTimeofDay field to set the same field on the Drivers assigned to it upon creation. The full address is divided up into separate fields and a corresponding timezone. There is also an optional terminalCode field as an alternate way to identify the Terminal on a per Account basis.

Tag Data Type Required Description
accountId Long No The id of the Account that owns this record.
city Text (unlimited) No The city where the Terminal is located
country Text (unlimited) No The country where the Terminal is located. Can be:

  • USA
  • Canada
  • Mexico
deletedAt Text (unlimited) No Indicates the date and time when the Terminal 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 Terminals that have not been soft-deleted.
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)
latitude Double Precision Auto Indicates the latitude coordinate of the location where the Terminal is located
longitude Double Precision Auto Indicates the longitude coordinate of the location where the Terminal is located
mainOffice Boolean No Indicates if the Terminal is the main office or not. Only one Terminal can be main office at a time. Setting this to true for one Terminal will set all other Terminals to false
name Text (unlimited) Yes The name of the Terminal
phoneNumber Character (50) No The phone number of the Terminal
postalCode Text (unlimited) No The postal code where the Terminal is located
startTimeOfDay Text Yes The start time of day set for the terminal
Note: Format must be in (HH:MM:SS)
state Text (unlimited) No The state where the Terminal 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) No The street where the Terminal is located
terminalCode Text (unlimited) No The optional in-account code used to identify the Terminal
timeZone Text (unlimited) Yes

Time zone where the Terminal 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/terminals
METHOD: GET
PARAMETERS: name – Retrieves matching records with the specific name (e.g. name=Terminal1, all Terminals by default)
terminal-code – Retrieves matching records with the specific terminalCode (e.g. terminal-code=HT-001, all Terminal codes 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=2016-11-11T06:57:06.629Z, null by default – returns only non-deleted records)
offset – Retrieves matching records after an offset value (e.g. offset=2)
limit – Retrieves a number of records per page specified by the value (e.g. limit=10)
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
QUERY STRING EXAMPLES: Get the Terminal with the specified id: api/v2/terminals/39
Get two Terminals of the current Account with an offset of 1 : ?offset=1&limit=2
Get all Terminals of the current Account sorted by name alphabetically: ?sort=name
EXAMPLE RESPONSE:
[
  {
    "name": "Terminal1",
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "Indiana",
    "postalCode": "46405",
    "country": "United States of America",
    "timeZone": "CST6CDT",
    "startTimeOfDay": "00:00:00",
    "terminalCode": "HT-001",
    "latitude": 41.8911622,
    "longitude": -87.6235815,
    "mainOffice": true,
    "phoneNumber": "1223334444",
    "accountId": 1248100,
    "id": 39,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Create

API PATH: /api/v2/terminals
METHOD: POST
REQUIRED FIELDS: name, startTimeOfDay
EXAMPLE REQUEST:
[
  {
    "name": "Terminal1",
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "Indiana",
    "postalCode": "46405",
    "country": "United States of America",
    "timeZone": "CST6CDT",
    "startTimeOfDay": "00:00:00",
    "terminalCode": "HT-001",
    "mainOffice": false,
    "phoneNumber": "1223334444"
  }
]
EXAMPLE RESPONSE:
[
  {
    "name": "Terminal1",
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "Indiana",
    "postalCode": "46405",
    "country": "United States of America",
    "timeZone": "CST6CDT",
    "startTimeOfDay": "00:00:00",
    "terminalCode": "HT-001",
    "latitude": 41.8911622,
    "longitude": -87.6235815,
    "mainOffice": false,
    "phoneNumber": "1223334444",
    "accountId": 1248100,
    "id": 39,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Update

API PATH: /api/v2/terminals
METHOD: PUT
EXAMPLE REQUEST:
[
  {
    "name": "Terminal2",
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "Indiana",
    "postalCode": "46405",
    "country": "United States of America",
    "timeZone": "CST6CDT",
    "startTimeOfDay": "01:00:00",
    "terminalCode": "HT-001",
    "mainOffice": true,
    "phoneNumber": "1223334444",
    "id": 39
  }
]
EXAMPLE RESPONSE:
[
  {
    "name": "Terminal2",
    "street": "Central Avenue. Lake Station",
    "city": "Lake County",
    "state": "Indiana",
    "postalCode": "46405",
    "country": "United States of America",
    "timeZone": "CST6CDT",
    "startTimeOfDay": "01:00:00",
    "terminalCode": "HT-001",
    "latitude": 41.8911622,
    "longitude": -87.6235815,
    "mainOffice": true,
    "phoneNumber": "1223334444",
    "accountId": 1248100,
    "id": 39,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Delete

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

Drivers assigned under the deleted Terminal are moved to the default main office Terminal. Delete for the Terminals API is implemented using a soft-delete. This prevents SQL’s Cascade Delete from deleting any driving records associated with a deleted Terminal.  Eventually, following the motor carrier’s data retention policy, the soft-delete will become a hard-delete.

Single Nearest Terminal

API PATH: /api/v2/terminals/meta/nearest
METHOD: GET
PARAMETERS ?lat=40.484674&long=-88.984680
EXAMPLE REQUEST:
[
  {
    "id": 183,
    "name": "Loc1",
    "latitude": 41.4851517,
    "longitude": -88.98509159999999,
    "distance": 0.063,
    "terminalCode": "HT-001"
  }
]

Multiple Nearest Terminals

API PATH: /api/v2/terminals/meta/nearest
METHOD: POST
EXAMPLE REQUEST:
[
  {
    "correlationId": 225,
    "lat": 44.223,
    "long": -88.4422
  },
  {
    "correlationId": 226,
    "lat": 20.223,
    "long": -90.73
  }
]
EXAMPLE RESPONSE:
[
  {
    "correlationId": 225,
    "terminals": [
      {
        "id": 4320454,
        "name": "Chicago Navy Pier Branch Terminal",
        "latitude": 44.222,
        "longitude": -88.4421,
        "distance": 71.84,
        "terminalCode": "HT-001"
      }
    ]
  },
  {
    "correlationId": 226,
    "terminals": [
      {
        "id": 5322555,
        "name": "A Terminal Near This Location",
        "latitude": 20.34,
        "longitude": -91.4,
        "distance": 400.84,
        "terminalCode": "HT-002"
      }      
    ]
  }
]

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 
Terminal should have a name. 500 7000 POST error because the Terminal must have a name
Terminal should have a value for Start Time of Day. 500 7000 POST error because the Terminal must have a Start Time of Day
Unable to save record 500 500 POST or PUT error because required fields are missing or incorrect
Access Denied. User is not authorized for this request.
403
8000
POST and PUT methods require permission of PERM_IS_ACCOUNT_ADMIN and PERM_EDIT_TERMINALS
DELETE method require permission of PERM_EDIT_TERMINALS
Unable to save the Terminal. Name already in use. 500 1001 POST or PUT error because the Terminal name is already used by another Terminal.
Unable to save the Terminal. Terminal Code already in use. 500 1001 POST or PUT error because the Terminal Code is already used by another Terminal.
Cannot find requested entity. (id = <id>) 500 3000 PUT or DELETE error because the supplied id does not exist
Main Office Terminal cannot be deleted 500 11000 DELETE error because a Terminal that is set as main office cannot be deleted
Error while handling request 500 500 Generic error message. Something is wrong with the request