Stop Arrival

7 min

When the truck arrives at a stop, the following notification will be POSTed to the callback URL.

Note: If you want the StopReferenceNumbers & EncryptedURL to be sent in callbacks, you need to have the Stop Reference Numbers & Encrypted URL feature flags enabled.

Request Parameter

{
"MessageType": "STOP_ARRIVAL",
"FourKitesLoadId": 1234,
"LoadNumber": "BOL12345",
"ProNumber": "PRO123",
"BillofLading": "bill_of_lading",
"BookingNumber": "booking_number",
"dataSource": "fourkites-x",
"VesselName": "DDC CMD 256AC",
"ContainerType": "40FT",
"ContainerNumber":"BEAU5912889",
"VoyageNumber": "108EE",
"Scac": "CC79",
"Shipper": "test-shipper",
"StopReferenceNumbers": [
"994891893",
"57348",
],
"EncryptedAccessToken": "VjJ8Z3NzaGlwcGVyfDYxNmJiYjYzLTgxYzxxxxxxxxxxYzgyLTE2ZWI3YWJhMzhjZQ",
"EncryptedUrl": "https://app.fourkites.com/#/integrations/trackLoad/v2/VjJ8Z3NzaGlwcGVyfDYxNmJiYjYzLTgxYzxxxxxxxxxxYzgyLTE2ZWI3YWJhMzhjZQ",
"Tags": ["tag1", "tag2"],
"StopUnlocode": "XXXX",
"ReferenceNumbers": ["ref1", "ref2"],
"StopReferenceId": "1",
"StopSequence": 1,
"StopStatus": "at_facility",
"OdometerReading": 12345.6,
"StopName": "ABC Stop",
"StopType": "pickup",
"DeviceID": "7645235",
"Timestamp": "2015-10-01T16:00:00-05:00",
"Timezone": "America/New_York",
"TimezoneShortName": "EST",
"TimezoneOffset" : -1800
}

The Stop Arrival message is generic for all stop types. This means that the format is canonical across modes. However, the way the callback differentiates the stop and it's type is the following fields:

StopName

StopReferenceId

StopSequence

StopType

Below is an example of these fields for a TL pickup stop:

{
    ...
    "StopName": "FourKites HQ",
    "StopReferenceId": "123",
    "StopSequence": 1,
    "StopType": "pickup"
    ...
}

Below is an example of a TL delivery stop:

{
    ...
    "StopName": "FourKites Delivery",
    "StopReferenceId": "456,
    "StopSequence": 2,
    "StopType": "delivery"
    ...
}

Field Definitions

Field Name	Description	Key Always Present?	Value Always Present?	Conditions for the Key to be Present	Data Type	Max Length
FourKitesLoadId	FourKites generated unique Load ID	Yes	No	N/A	Number	20
LoadNumber	Customer supplied Load Number. This is populated on the Create Load API	Yes	No	N/A	String	65535
ProNumber	PRO Number associated with the load	Yes	No	N/A	Number	10
ReferenceNumbers	List of unique identifiers for the load. These can be used to search for the load the platform	Yes	No	N/A	Array of string	No max
Scac	SCAC or identifier for the carrier	Yes	No	N/A	Alpha/Numeric	4
Shipper	Unique permalink for the company. This is generated by FourKites and is unique for each company	Yes	No	N/A	String	No max, but realistically, not longer than 200 characters
StopName	Stop name which was just arrived at	Yes	Yes	N/A	String	No max
StopReferenceId	Unique identifier for the stop. This identifier is defined when creating the load	Yes	No	N/A	string	1024
StopSequence	StopSequence indicates the numerical or textual position of the stop that was just arrived at within the load's overall journey. The value format exported in the callback will match how your organization initially created loads—either as an integer or string. StopSequence values can dynamically change during transport when routing is modified, such as when a transshipment port or hub airport is added to optimize the journey. For certain transportation types like ocean loads, 'hidden' operational stops may exist in the system, causing visible stops to begin with a higher StopSequence value than expected.	Yes	No	N/A	Number	10
StopStatus	Status of the current stop. When delivered on the Stop Arrival callback, this value will most often be "at_facility" and "at_airport" for Air loads.	Yes	No	N/A	String
StopType	Type of stop which was just arrived at. Can be one of the following values: * Pickup

Terminal

port_of_loading (not common)

transhipment_port

port_of_discharge

place_of_delivery

Origin Airport

Hub Airport

Destination Airport

Delivery | Yes | No | 1. If the transportation mode is ocean and if the stopType is pickup, it will be mapped as Port of Loading 2. If the stopType is transfer for an Ocean load, it will be mapped as TranshipmentPort. 3. If the load is Air, and if the stopType is pickup then the field will be mapped as as origin airport. 4. If the load is Air, and if the stopType is Delivery then the field will be mapped as destination airport. 5. If the load is Air, and if the stopType is transfer then the field will be mapped as hub airport. 6. If the transportation mode is not ocean and air, it will be mapped directly to the value sent by the customer during load creation. | String | 1024 | | Tags | List of categories or labels for the load | Yes | No | N/A | Array of string | 50 for each tag | | Timestamp | Time that the stop was arrived at. This will be in the local time of the stop | Yes | Yes | The ArrivedAt field will be converted to specific timezone and will mapped as Timestamp. | String in DateTime format | | | Timezone | Time zone of the stop | Yes | Yes | N/A | String | 50 | | TimezoneOffset | Numeric offset (in seconds) of the stop's time zone | Yes | No | Depends on timestamp, if the timestamp is empty/null, it will not be mapped. | [+/-]Digits | 10 | | TimezoneShortName | Time zone short name of the stop | Yes | No | If Timestamp or Timezone is nil then TimezoneShortName will be empty | String | 5 | | EncryptedAccessToken | A token which can be appended to a FourKites URL host to create a "shared shipment status" URL for the specific delivery stop. Please contact FourKites for more information | No | No | If encrypted access token is not null and StopType is delivery, the field EncryptedAccessToken will be mapped. | String | 2048 | | EncryptedURL | Encrypted URL of the load which is unique and which can be used to access details of the load | No | No | If the StopType is delivery then the EncryptedURL field will be mapped based on a license. It's a feature flag. | String | 1024 | | StopUnlocode | It indicates the UNLOCODE of the stop. (Specific to Ocean load modes.) | No | No | If the transportation mode is ocean, and the stoptype is port of loading, port of discharge and transhipment port, then the field StopAddressID will be mapped as StopUnlocode. | String | | | StopReferenceNumbers | | No | No | Feature Flag. It will be mapped directly if the customer is licensed for it. | Array | no max size | | OdometerReading | | No | No | Will be mapped only based on the Odometer field received with the reading. If it is null, it will not be mapped. | | | | BookingNumber | Booking number provided for tracking the shipment | Yes | Yes | For Ocean Loads. | String | 1024 | | VoyageNumber | Number of the voyage for the vessel the shipment is currently loaded on | Yes | Yes | For Ocean Loads. | String | | | VesselName | Name of the vessel the shipment is currently loaded on | Yes | Yes | For Ocean Loads. | String | 1024 | | ContainerType | Type of the container in which the shipment is loaded | Yes | Yes | For Ocean Loads. | String | 1024 | | ContainerNumber | Number of the container in which the shipment is loaded | Yes | Yes | For Ocean Loads. | String | 1024 | | BillOfLading | MBOL or HBOL provided for tracking the shipment | Yes | Yes | For Ocean Loads. | String | 1024 | | TerminalName | It indicates the terminal inside a port where the vessel is berthing (terminal name tied to a stop). Applicable for messages tied to following stoptypes: - port_of_loading - transhipment_port - port_of_discharge | Yes | Yes | For Ocean Loads. | String | | | CreatedBy | This applies only for FourKites X loads. To learn more about FourKites X, refer here. | Yes, if it's a FourKites X Load. | Yes, if it's a FourKites X Load. | The CreatedBy field will be available and sent only for FourKites X licensed customers — this is to identify between FourKites X and non FourKites X loads. To learn more about FourKites X, refer here. | String | 1024 |