(Legacy) Dispatcher Update

9 min

The Dispatcher Update API allows authorized carriers and fleet owners to update loads in bulk. For example, you can use this API to update tracking information or stop appointment time for multiple loads at a time. The Dispatcher Update API supports any number of records. However, the records are processed in batches of 50.

Rate Limit

60 requests per minute

Click here for more information on Rate Limit.

The Legacy Dispatcher Update API does not support intermodal terminal stop creation. To create or update terminal stops programmatically, use the Dispatcher Update Asynchronous API instead, which supports terminal stop creation via the stopUpdate terminalStops array.

Format Supported

JSON

Authenticated Resource

API Key

For more information on Authentication, click here.

Production

POST

https://api.fourkites.com/api/v1/tracking/dispatcher_updates

curl --location --request POST 'https://api.fourkites.com/api/v1/tracking/dispatcher_updates' \
--header 'Content-Type: application/json' \
--header 'apikey: REPLACE_KEY_VALUE' \
--data-raw '{
    "updates": [
        {
            "shipper": "Shippers ExternalID",
            "billOfLading": "BOL of the Load",
            "timeZone": "America/Chicago",
            "carrierMatchingNumber": "Carrier Matching Number",
            "proNumber": "PRO number of the load",
            "operatingCarrierScac": "Operating Carrier SCAC ID",
            "truckNumber": "Truck Number as in the GPS/ELD portal",
            "trailerNumber": "Trailer Number as in the GPS/ELD portal",
            "driverPhone": "Phone Number with the Country Code",
            "railEquipmentInitials": "XYZ1",
            "railEquipmentNumber": "ABC",
            "wagonNumber": "qwerty123",
            "inGateTime": "YYYY-MM-DDTHH:MM:SS",
            "outGateTime": "YYYY-MM-DDTHH:MM:SS",
            "shipmentStatus": "Shipment Status",
            "shipmentStatusIndicator": "Shipment Status Indicator",
            "railEventCode": "Rail event code",
            "containerNumber": "LRGA12345677",
            "eventCode": "RD",
            "eventTimestamp": "YYYY-MM-DDTHH:MM:SS",
            "portCode": "CAHAL",
            "vesselName": "MSC PARIS",
            "vesselNumber": "1234567",
            "latitude": "41827892",
            "longitude": "-87.622003",
            "city": "Chicago",
            "state": "IL",
            "country": "USA",
            "mmsi": "123456789",
            "locatedAt": "YYYY-MM-DDTHH:MM:SS",
            "earliestAppointmentTime": "YYYY-MM-DDTHH:MM:SS",
            "latestAppointmentTime": "YYYY-MM-DDTHH:MM:SS",
            "stopSequence": "2",
            "postalCode": "75201",
            "stopReferenceId": "61224043",
            "stopId": "61224043",
            "statusCode": "X3",
            "statusDescription": "X3 At pickup Message",
            "statusReasonCode": "Late Reason Code for the load",
            "delivered": "true",
            "deliveredAt": "YYYY-MM-DDTHH:MM:SS",
            "deliveryTime": "YYYY-MM-DDTHH:MM:SS",
            "pickupTime": "YYYY-MM-DDTHH:MM:SS",
            "estimatedArrivalAtDestination": "YYYY-MM-DDTHH:MM:SS",
            "brokeredLoad": "True",
            "relayLoad": "Yes",
            "temperature": "12",
            "sensorName": "TestSensor",
            "temperatureUnit": "C",
            "temperatureCheckCallTime": "YYYY-MM-DDTHH:MM:SS",
            "weight": "12",
            "weightUnit": "LB",
            "freightCharges": "100",
            "freightChargeUnit": "USD",
            "quantity": "100",
            "tags": [
                "tag1",
                "tag2"
            ],
            "simultaneousTrackingReferenceNumber": "sim007654",
            "simultaneousTrackingSequenceNumber":  1,
            "serviceLevel": "overnight",
            "deliveryType": "live",
            "stopReferenceNumber": "stopReferenceNumber",
            "stopTracking": "true",
            "updateType": "Rail",
            "forceStart": "true",
            "additionalData": {
                "stopStatus": {
                    "stopId": 61224043,
                    "code": "AF",
                    "description": "",
                    "city": "",
                    "state": "",
                    "country": "",
                    "date": "2020-02-04T06:30:00.000Z"
                }
            }
        }
    ]
}'

Staging

POST

https://api-staging.fourkites.com/api/v1/tracking/dispatcher_updates

import http.client
import json

conn = http.client.HTTPSConnection("api-staging.fourkites.com")
payload = json.dumps({
  "updates": [
    {
      "shipper": "Shippers ExternalID",
      "billOfLading": "BOL of the Load",
      "timeZone": "America/Chicago",
      "carrierMatchingNumber": "Carrier Matching Number",
      "proNumber": "PRO number of the load",
      "operatingCarrierScac": "Operating Carrier SCAC ID",
      "truckNumber": "Truck Number as in the GPS/ELD portal",
      "trailerNumber": "Trailer Number as in the GPS/ELD portal",
      "driverPhone": "Phone Number with the Country Code",
      "railEquipmentInitials": "XYZ1",
      "railEquipmentNumber": "ABC",
      "wagonNumber": "qwerty123",
      "inGateTime": "YYYY-MM-DDTHH:MM:SS",
      "outGateTime": "YYYY-MM-DDTHH:MM:SS",
      "shipmentStatus": "Shipment Status",
      "shipmentStatusIndicator": "Shipment Status Indicator",
      "railEventCode": "Rail event code",
      "containerNumber": "LRGA12345677",
      "eventCode": "RD",
      "eventTimestamp": "YYYY-MM-DDTHH:MM:SS",
      "portCode": "CAHAL",
      "vesselName": "MSC PARIS",
      "vesselNumber": "1234567",
      "latitude": "41827892",
      "longitude": "-87.622003",
      "city": "Chicago",
      "state": "IL",
      "country": "USA",
      "mmsi": "123456789",
      "locatedAt": "YYYY-MM-DDTHH:MM:SS",
      "earliestAppointmentTime": "YYYY-MM-DDTHH:MM:SS",
      "latestAppointmentTime": "YYYY-MM-DDTHH:MM:SS",
      "stopSequence": "2",
      "postalCode": "75201",
      "stopReferenceId": "61224043",
      "stopId": "61224043",
      "statusCode": "X3",
      "statusDescription": "X3 At pickup Message",
      "statusReasonCode": "Late Reason Code for the load",
      "delivered": "true",
      "deliveredAt": "YYYY-MM-DDTHH:MM:SS",
      "deliveryTime": "YYYY-MM-DDTHH:MM:SS",
      "pickupTime": "YYYY-MM-DDTHH:MM:SS",
      "estimatedArrivalAtDestination": "YYYY-MM-DDTHH:MM:SS",
      "brokeredLoad": "True",
      "relayLoad": "Yes",
      "temperature": "12",
      "sensorName": "TestSensor",
      "temperatureUnit": "C",
      "temperatureCheckCallTime": "YYYY-MM-DDTHH:MM:SS",
      "weight": "12",
      "weightUnit": "LB",
      "freightCharges": "100",
      "freightChargeUnit": "USD",
      "quantity": "100",
      "tags": [
        "tag1",
        "tag2"
      ],
      "simultaneousTrackingReferenceNumber": "sim007654",
      "simultaneousTrackingSequenceNumber": 1,
      "serviceLevel": "overnight",
      "deliveryType": "live",
      "stopReferenceNumber": "stopReferenceNumber",
      "stopTracking": "true",
      "updateType": "Rail",
      "forceStart": "true",
      "additionalData": {
        "stopStatus": {
          "stopId": 61224043,
          "code": "AF",
          "description": "",
          "city": "",
          "state": "",
          "country": "",
          "date": "2020-02-04T06:30:00.000Z"
        }
      }
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'apikey': 'REPLACE_KEY_VALUE'
}
conn.request("POST", "/api/v1/tracking/dispatcher_updates", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Request Parameters Table

Object	Attribute	Format	Modes	Validation	Description	Mandatory (M)/Conditional Mandatory (CM)/Optional (O)
updates	shipper	String	All	External ID is mandatory for assigning an operating carrier SCAC.	It is the unique FourKites® ID of the shipper.	M for 3PL customers
updates	billOfLading	String	TL,LTL,Parcel,Rail,Ocean		It indicates the bill of lading associated with the Ocean load.	O
updates	railEquipmentInitials	String	Rail		Enter the 2 to 4 character rail equipment prefix.	Mandatory for Rail updates
updates	railEquipmentNumber	String	Rail		Enter the 3 to 6 digit rail equipment number.	Mandatory for Rail updates
updates	wagonNumber	String	Rail		Enter the Wagon Number if applicable.	O
updates	updateType	String	Rail		The updateType value should be 'rail' when the carrier is unable to send Rail Equipment Initials & Number. Refer to the note below for more info.	O, Mandatory when the carrier is not able to send standard status code.
updates	railEventCode	String	Rail		Enter any standard or custom status code. Note: The mapping should also be updated in FourKites for the standard code type that is being sent; get in touch with your POC at FourKites to do this.	O
updates	inGateTime	String	Rail		Rail Load specific update	O (Mandatory for tracking dray)
updates	outGateTime	String	Rail		Rail Load specific update	O (Mandatory for tracking dray)
updates	containerNumber	String	Ocean		It indicates the vessel number.	M
updates	eventCode	String	Ocean	Enter any one of the following Events such as I, AE, VD, VA, UV, OA, D, RD, AG, C1.	Enter Ocean Event Codes	M
updates	portCode	String	Ocean		The unlocode of the port where the event occurs.	M
updates	vesselName	String	Ocean		Vessel name associated with the load	M
updates	vesselNumber	String	Ocean		Vessel IMO associated with the load	O
updates	mmsi	String	Ocean		Vessel MMSI associated with the load	O (recommended for Barge)
updates	opearatingCarrierScac	String	All		Enter the SCAC assigned by a Managing Carrier (3PL or broker) to an Operating Carrier. When a Carrier brokers out a load to another Operating Carrier, this field will be used to identify the load in an operating carrier's file.	O
updates	truckNumber	Integer	TL, LTL, Parcel		Enter the tractor number assigned to the load. Mandatory if tracking via the truck is primary method.	O
updates	trailerNumber	Integer	TL, LTL, Parcel		Enter the trailer number assigned to the load. Mandatory if tracking via the trailer is primary method.	O
updates	driverPhone	Integer	TL, LTL, Parcel		Enter the phone number of the driver currently assigned to the load. Mandatory if tracking via mobile device is primary method. The phone number must start with a "+" sign followed by the ISD code and then the mobile number.	O (Mandatory for brokered loads)
updates	city	String	TL,LTL,Parcel,Rail		It indicates the name of the city.	M
updates	state	String	TL,LTL,Parcel,Rail	It is the 2 character State Code for US & Canada and 3 Character State Code for Mexico.	It indicates the 2 character state code for US & Canada and 3 Character state code for Mexico.	M
updates	postalCode	String	TL,LTL,Parcel,Rail		It indicates the valid postal code for the stop.	O
updates	country	String	TL,LTL,Parcel,Rail	It is the 2 digit country code.	It indicates the valid country code.	O
updates	latitude	String	TL,LTL,Parcel,Rail	It is formatted to decimal degrees.	It indicates the latitude of the stop's location.	O
updates	longitude	String	TL,LTL,Parcel,Rail	It is formatted to decimal degrees.	It indicates the longitude of the stop's location.	O
updates	locatedAt	String	TL,LTL,Parcel,Rail		Enter the timestamp at which the latitude and longitude values were recorded for location. This field is usually given along with the latitude/longitude values. If no value is given, the current time will be considered as locatedAt value.	locatedAt OR eventTimestamp is Mandatory for Rail updates
updates	earliestAppointmentTime	String	All		Enter the earliest scheduled arrival time for the stop in stop's local timezone, given in ISO 8601 format. To update a stop's appointment time, the stopSequence or the stopReferenceId should also be specified. If you wish to provide a single appointment time and not a time range, use the same value here as with latestAppointmentTime.	O
updates	latestAppointmentTime	String	All		Enter the latest scheduled arrival time for the stop in stop's local timezone, given in ISO 8601 format. To update a stop's appointment time, the stopSequence or the stopReferenceId should also be specified. If you wish to provide a single appointment time and not a time range, use the same value here as with earliestAppointmentTime.	O
updates	stopSequence	String	All		Enter the stop sequence of the stop. The stopSequence is used to identify the stop for which the appointment time or status reason code is updated. Note: This stop sequence you specify should be present at the stop in the load (BOL) mentioned. For example, if you wish to update the appointment time or reason code for a stop with stop sequence 2, enter the value as 2.	O
updates	statusCode	String	TL		Use this field to update the load status of a TL load	O
updates	statusReasonCode	String			Enter the reason codes. Currently, there are no specific codes. Carriers can add any string value. A carrier can update reason codes at a load level or stop level. To update reason codes at a stop level, the corresponding stopReferenceId or stopSequence of the stop should also be specified.	O
updates	statusDescription	String	All		Use this field to specify the description of the LTL load status	Optional, use this when status code specified
updates	delivered	Boolean	All		Enter true or false. If the load is delivered, delivered flag should be set to true. If the load is not delivered, delivered flag need not be included. This is JSON boolean field.	M
updates	deliveredAt	String	All		Enter the time (in UTC) at which the shipment was delivered at the final consignee. If the "delivered" parameter is passed as True, this value should be provided to indicate the time of load delivery. If no value is given, deliveredAt will default to the current time.	M
updates	pickupTime	String	All		Time when the load was picked up	O
updates	deliveryTime	String	All		Time when the load was delivered	O
updates	estimatedArrivalAtDestination	String	All		ETA to destination provided by the carrier	Optional, Required if no other location information is being provided
updates	carrierMatchingNumber	String	All		For referencing loads between managing & operating carriers.	O
updates	brokeredLoad	Boolean	All		It indicates if the load is a brokered load or not.	Optional, Required if the load is brokered and must be indicated on the load card.
updates	relayLoad	Boolean	TL	Valid values: true or false. Defaults to false.	It indicates whether the load is a relay load or a team load.	O

The following table will include load identifiers that will act as separate fields:

Object	Attribute	Format	Modes	Description	Mandatory (M)/Conditional Mandatory (CM)/Optional (O)
updates	postalCode	String	All	It indicates the postal/zip code of the stop.	O
updates	loadNumber	String	TL,LTL,Parcel,Rail,Ocean	It indicates the load number.	O
updates	loadTrackingNumber	String	All	It indicates the load’s tracking number.	O
updates	loadReferenceNumber	String	All	It indicates the load’s reference number.	O
updates	proNumber	String	All	It indicates the PRO number of the load.	O
updates	poNumber	String	All	It indicates the PO (Purchase Order) number of the load.	O
updates	stopTrackingNumber	String	All	It indicates the tracking number of the stop.	O
updates	tags	Array	All	It indicates the tag specified by a company for a load.	O
updates	stopTracking	String	All	It indicates that the tracking of the load is stopped.	O
updates	forceStart	String	All	It indicates the timestamp of the sequenced load is due to start tracking.	O
updates	deliveryType	String	All	It indicates the delivery type of the load.	O
updates	serviceLevel	String	All	It indicates the time period for loading or unloading.	O

For any load update, the shipper and billOfLading fields are mandatory.

The only accepted format of lat/long by FourKites is the "Decimal Degrees" format. For example, 41.8781 (lat), -87.6298 (long).

To update a stop's appointment time, you must additionally specify the stopSequence or stopReferenceId values. These values are used to identify and match the stop for which the appointment time will be updated. If stopSequence or stopReferenceIdvalue values are not specified, the appointment time will not be updated.

Appointment times cannot be more than 4 days in the past from the current time.

locatedAt timestamps have to be less than 6 hours old or 5 minutes in the future.

deliveredAt timestamps have to be less than 24 hours old or 5 minutes in the future.

Passing the delivered parameter will mark the load as Delivered. Currently, it is not possible to mark a specific stop as complete using this API.

You can update the status reason codes at a load level or stop level. If you want to update status reason codes at a stop level, specify the corresponding stopSequence or stopReferenceId.

The statusCode and statusDescription sent will be available in the load's Tracking Updates/Notes section

additionalData is applicable only for companies enabled with Smart Forecasted Arrival where code "X3" will mark the load as "At Pickup" and code "AF" will mark the load as "Picked Up".

In the additionalData segment, note that the "stopReferenceID" field is also accepted.

The possible event codes that Carrier can send for Ocean Loads includes: I - In-Gate AE - Loaded on Vessel VD - Vessel Departure VA - Vessel Arrival UV - Unloaded From Vessel OA - Out-Gate D - Arrival At Delivery RD - Return Container AG - ETA Update C1 - ETD Update

If you are not able to send standard status codes, the updateType should be sent as 'rail'. However, get in touch with FourKites to map the custom status codes.

Load Mode Detection

"additionalData": { "modeDetails":{ "shipperModes": "", "carrierModes": "" } },

Now, Shippers, 3PLs and Carriers have the ability to set the Load Mode (TL, LTL, Rail, Ocean or Parcel) of a load. The load creators can specify the load mode using the Load Create and Load Update API and carriers can specify the load mode using Truck Assignment API, Dispatcher update API, Locations API and Batch Locations API.

However, if both the load creator and carrier sends different load modes, we can define a rank order of which source is the most trustworthy.

For example, let's consider the priority is set as Carrier > Shipper > FourKites®. Carrier sends mode as “TL” while shipper sends it as “LTL” and FK detects it as “LTL”. In this case the load will track as TL only.

By default, we will track the load mode detected by FourKites® but to set a ranking order, please speak to your CSM at FourKites.

Response Attributes

Name	Format	Description
message	String	It represents the status of the request submitted.
statusCode	String	HTTP StatusCode of the response.