--- title: Stop Departure slug: fourkites-api-reference/stop-departure description: Learn about the Stop Departure callback sent by FourKites when a vehicle deviates from its assigned stop. This document covers the variations of the callback based on the mode of transportation, along with a detailed explanation of each field included in createdAt: 2023-04-14T06:09:48.000Z --- 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 :::hint{type="info"} If you want the `StopReferenceNumbers` & `EncryptedURL` to be sent in callbacks, you need to have the Stop Reference Numbers & Encrypted URL feature flags enabled. ::: :::hint{type="info"} `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 ```json { "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: ```json { ... "StopName": "FourKites HQ", "StopReferenceId": "123", "StopSequence": 1, "StopType": "pickup" ... } ``` Below is an example of a TL delivery stop: ```json { ... "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: ```json { "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: ```json { "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 |