Stop Departure

7 min

The Stop Departure callback is sent as soon as FourKites receives a GPS ping outside the geofence of the stop which was previously arrived. Alternatively, for modes which use status-based tracking, this could be delivered directly as a status from the carrier. Below are the variations by mode:

TL: GPS ping outside stop geofence after previously being marked as arrived

LTL / Parcel: GPS ping outside stop geofence after previously being marked as arrived (if using GPS tracking) or status of AF / CD / D1 from the carrier

Rail / Intermodal: GPS ping outside stop geofence after previously being marked as arrived (if using GPS tracking) or status of AF / CD / D1 from the carrier

Ocean: GPS ping outside the port geofence or a status of VD from the shipping line

Air: GPS ping outside the airport geofence or a status of AF / D1 from the airline

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

StopSequence will change dynamically as and when new stops are created using carrier data. Hence, it is recommended to use StopTypes instead for mapping.

Request Parameter

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

The Stop Departure 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 its 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"
    ...
}

When FourKites does not detect the stop departure (auto-completion or manual completion), the following notification will be POSTed to the callback URL.

Sample callback when the stop is manually picked up:

{
 "MessageType": "MANUALLY_PICKED_UP",
 "FourKitesLoadId": 1689,
 "LoadNumber": "Sample_test_load",
 "Mode": "Web",
 "ProNumber": null,
 "ReferenceNumbers": null,
 "Scac": "TL",
 "Shipper": "testshipper",
 "StopName": "Stop 1",
 "DepartedAt": "2018-11-18T06:00:00-06:00",
 "StopReferenceId": 73246,
 "StopSequence": 1,
 "StopType": "pickup",
 "Tags": null,
 "Timestamp": "2018-11-19T04:13:38-06:00",
 "Timezone": "America/Chicago",
 "TimezoneOffset": -21600,
 "TimezoneShortName": "CST"
}

Sample callback when the stop is manually delivered:

{
 "MessageType": "MANUALLY_DELIVERED",
 "FourKitesLoadId": 1689,
 "LoadNumber": "Sample_test_load",
 "Mode": "Web",
 "ProNumber": null,
 "ReferenceNumbers": null,
 "Scac": "TL",
 "Shipper": "testshipper",
 "StopName": "Stop 2",
 "DepartedAt": "2018-11-18T15:00:00-06:00",
 "StopReferenceId": 23423,
 "StopSequence": 2,
 "StopStatus": "Completed",
 "StopType": "delivery",
 "Tags": null,
 "Timestamp": "2018-11-19T04:26:46-06:00",
 "Timezone": "America/Chicago",
 "TimezoneOffset": -21600,
 "TimezoneShortName": "CST"
}

Field Definitions

Field Name	Description	Key Always Present?	Value Always Present?	Conditions for the Key to be Present	Data Type	Max Length
AutoDeparture	In rare cases, we receive arrival but not departure info for the final delivery stop on a load. When this happens, FourKites marks these stops as completed by auto-departure. This is a boolean value: true/false.	Yes	No	N/A
FourKitesLoadId	Unique load identifier from FourKites system if the load was successfully created (IsSuccess = true). The field will be null if the load creation failed in FourKites	Yes	No	N/A	Number	20
LoadNumber	Unique shipment identifier from shipper's system	Yes	No	N/A	String	65535
ProNumber	Shipment's PRO #	Yes	No	N/A	Number	10
ReferenceNumbers	List of additional reference numbers associated with the load (empty list when no reference numbers are associated with the load)	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 shipper ID from FourKites	Yes	Yes	N/A	String	No max, but realistically, not longer than 200 characters
StopName	Name of the stop provided during load creation	Yes	Yes	N/A	String	No max
StopReferenceId	Reference ID of the stop provided during load creation	Yes	No	N/A	string	1024
StopSequence	Sequence of the stop on the load that the truck departed from	Yes	No	N/A	Number	10
StopStatus	Status of the current stop. When delivered on the Stop Departure callback, this value will most often be "completed"	Yes	No	N/A	String
StopType	Stop type - * 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 tags associated with the load (empty list when tags are not present) | Yes | No | N/A | Array of string | 50 for each tag | | Timestamp | Time when the truck departed the stop in stop's local time (in ISO 8601 format with local time offset to UTC) | Yes | Yes | The DepartedAt Time will be convert to different timezone and will be mapped as Timestamp. | String in DateTime format | 30 | | Timezone | Local Timezone of the stop in which Timestamp is specified. | Yes | No | | String | 50 | | TimezoneOffset | Number of seconds local timezone is ahead of UTC time. Negative for western hemisphere timezones. | Yes | No | Based on the Timestamp | [+/-]Digits | 10 | | TimezoneShortName | Short name of Timezone of the stop in which "Timestamp" is specified. | Yes | No | Based on both Timestamp and Timezone | String | 5 | | EncryptedAccessToken | The access token that would be used to create an encrypted URL. | Only for Delivery stops | Only for Delivery stops | If encrypted access token is not null and stoptype is delivery then 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 | Only for Delivery stops | Only for Delivery stops | If the StopType is delivery then the EncryptedURL field based on a license. Feature Flag | String | 1024 | | StopUnlocode | UNLOCODE of the port. Specific to Ocean loads. | 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 | List of reference numbers associated with the particular stop | No | No | As needed basis | Array | no max size | | BookingNumber | It indicates the shipping line's booking number. | Yes | Yes | For Ocean loads. | String | 1024 | | VoyageNumber | It indicates the unique identifier given for the voyage. | Yes | Yes | For Ocean loads. | String | 1024 | | VesselName | It indicates the name of the vessel carrying the load. | Yes | Yes | For Ocean loads. | String | | | ContainerType | It indicates whether the container is a general, high cube, Reefer, etc., type of container. | Yes | Yes | For Ocean loads. | String | 1024 | | ContainerNumber | Container Number of the ocean load | Yes | Yes | For Ocean loads. | String | 1024 | | BillOfLading | It indicates the bill of lading associated with the load. | 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. | | | 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. | String | 1024 |