Tracking Update

4 min

The update is sent whenever key Tracking Updates are made to the load.

{
    "MessageType" : "TRACKING_UPDATE",
    "FourKitesLoadId" : 1234,
    "LoadNumber" : "BOL12345",
    "deliveryNumbers": ["DN001", "DN002"],
    "masterTrackingNumber": "MTN12345", 
    "ProNumber" : "PRO123",
    "BargeId": "IN016574",
    "BargeStatus": "false",
    "CurrentPosition": "OH 123 T",
    "ContainerNumber":"BEAU5912889",
    "dataSource": "fourkites-x",
    "Shipper" : "test-shipper",
    "Scac" : "ABCD",
    "Tags" : ["tag1", "tag2"],
    "ReferenceNumbers" : ["ref1", "ref2"],
    "DeviceID": "64235",
    "Status" : "Delayed",
    "Message" : "Delay in loading at the stop",
    "StopName" : "ABC Stop",
    "StorageStatus" : "empty",
    "Timestamp" : "2015-10-01T16:00:00-05:00"
}

Field Definitions

Field Name	Description	Key Always Present?	Value Always Present?	Conditions for the Key to be Present	Data Type	Max Length
LoadNumber	Unique shipment identifier from shipper's system	Yes	Yes	N/A	String	65535
deliveryNumbers	It indicates that the load has delivery number values	No	No	If the values are available	String	No Limit
masterTrackingNumber	It indicates that the load has master tracking number value	No	No	If the value is available	String	No Limit
Message	Indicates the tracking update details. For example, "Driver 8221 assigned for tracking". For Air Split Shipments*, the message will display if any of the two (Active & Resolved splits) occur. Click here to learn more.	Yes	Yes	If Status = Driver Assigned, a field called Message will be mapped.	String	1024
ProNumber	Shipment's PRO #	Yes	No	N/A	Number	10
BargeId	It indicates the barge Load Identifier.	Yes	Yes	If the load is Barge load.	String	No max
BargeStatus	It indicates the barge status as true or false.	Yes	No	If the load is Barge load.	String	No max
CurrentPosition	It indicates barger Mile marker.	Yes	No	If the load is Barge load.	String	No max
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 of the carrier assigned to the shipment/load	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	Yes	N/A	String	No max, but realistically, not longer than 200 characters
Status	Indicates the stop's status. For Air Split Shipments, the Status will display split type. Click here to learn more.	Yes	Yes	N/A	String
StopName	Name of the stop provided during load creation. For Air Split Shipments, the StopName will show the name of the stop where the split took place. Click here to learn more.	Yes	No	N/A	String	No max
StorageStatus	Barge storage is Full/ Empty	Yes	No	If the load is Barge load.	String	No max
Tags	List of tags associated with the load (empty list when tags are not present)	Yes	No	Default value is UTC	Array of string	50 for each tag
Timestamp	The time in UTC when the callback was triggered	Yes	Yes	N/A	ISO8601 Date/Time
FourKitesLoadId	Unique load identifier from the FourKites system	Yes	No	N/A	Number	20
DeviceID	DeviceID assigned to the load	No	No	Feature Flag. It will be mapped directly if the customer is licensed for it.	String
StatusCode		No	No	FeatureFlag. Mapping it EDI Status Code field	String	50 at max
CreatedBy	This applies only for FourKites X loads.	Yes	Yes	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
EncryptedUrl	Shared shipment status URL which provides a link to a web page showing the current status of a load. No authentication is necessary to access the link	No	No	Only if the status is Container Assigned, we will be mapping it EncryptedUrl	String containing url	1024
BookingNumber	Booking number provided for tracking the shipment	No	No	Ocean	String	1024
VoyageNumber	Number of the voyage for the vessel the shipment is currently loaded on	No	No	Ocean	String
VesselName	Name of the vessel the shipment is currently loaded on	No	No	Ocean	String	1024
ContainerType	Type of the container in which the shipment is loaded	No	No	Ocean	String	1024
ContainerNumber	Number of the container in which the shipment is loaded	No	No	Ocean	String	1024
BillOfLading	MBOL or HBOL provided for tracking the shipment	No	No	Ocean	String	1024

Note: Get in touch with your Customer Success Manager at FourKites to know how to pass the DeviceID during load creation and have the same included in this callback.

Below is the list of tracking update statuses along with their messages that trigger this callback:

Status	Message
Tracking Info Unassigned	Load is past planned pickup appointment time
Truck Assigned/Trailer Assigned/Driver Assigned/Rail Equipment Assigned	Tracking information is assigned/updated
Tracking	Load has started receiving location updates
At Pickup	Truck is detected at the facility
Departed Pickup	Truck has departed facility
Picked Up	Load has been picked up by Geofence
Auto Pickup	Stop marked as picked up automatically (Arrival not detected by FourKites)
Rail Tracking Start	Tracking has started for Rail leg
Rail Tracking End	Tracking has ended for Rail leg
Intermodal Interchange	Intermodal Ingate
Intermodal Interchange	Intermodal Outgate
At Consignee	Truck is detected at the facility
Delivered	Marked as delivered by Geofence
Auto Delivery	Stop marked as delivered automatically (Arrival not detected by FourKites)
partially_picked_up/partially_delivered	Load is partially picked up/delivered
Manual Completion	Load has been manually completed
Tracking stopped by Carrier	Load has stopped tracking
Rescheduled	Load is rescheduled
Expired	Load has expired
Loaded on rail	Container/Trailer loaded on rail car
Intermodal Outgate	Intermodal OutgateIntermodal In-gate- Intermodal Ingate
Interchange delivery	Interchange delivery at location
Interchange receipt	Interchange receipt at location
Bad order	Bad order due to reason for x hours
Released from bad order	Rail Equipment issue Resolved
Hold	Held due to reason for x hours
Released from hold	Released From Hold
Border crossing	Railcar has crossed an international border
Unloaded from rail	Container/Trailer has been unloaded from Rail car
Rail destination arrival	Rail car arrived at the final destination
Constructive placement	Rail car is near or at customer site but has not yet been ordered placed by customer
Motor carrier departure	Motor Carrier Departure
Released empty	Rail car was released empty after unloading
Actual placement	Railcar is placed for unloading on the patron’s siding
Pulled into mainline	Rail car pulled from patron siding to the mainline
Motor carrier arrival	Motor Carrier Arrival
Hold for embargo	Hold for embargo
Released from embargo hold	Released from embargo hold
Notified destination party	Notified destination party
Loaded on chassis	Loaded on chassis
Unloaded from chassis	Unloaded from chassis
At Port of Loading	Vessel is detected at the facility
Departed Port of Loading	Vessel has departed facility
At Transshipment Port	Vessel is detected at the facility
Departed Transhipment Port	Vessel has departed facility
At Port of Discharge	Vessel is detected at the facility
Transshipment Change	New Transshipment port has been added to the shipment
Vessel Departure	Vessel has departed
Vessel Arrival	Vessel has arrived
Arrived at Origin Airport	The cargo has arrived at the Origin Airport.
Departed Origin Airport	The cargo has departed the Origin Airport
Arrived at Hub Airport	The cargo has arrived at the Hub Airport
Departed Hub Airport	The cargo has departed the Hub Airport
Arrived at Destination Airport	The cargo has arrived at Destination Airport
Departed Destination Airport	The cargo has departed the Destination Airport
Booking Confirmed	The space for cargo has been booked in advance.
On Rail to Origin Airport	The cargo is loaded onto Rail from pickup stop.
At Customs At Origin Airport	The cargo is awaiting customs clearance at Origin Airport
At Customs At Hub Airport	The cargo is awaiting customs clearance at Hub Airport
At Customs At Destination Airport	The cargo is awaiting customs clearance at Destination Airport
Customs Released At Origin Airport	The cargo has received customs clearance at Origin Airport
Customs Released At Hub Airport	The cargo has received customs clearance at Hub Airport
Customs Releases At Destination Airport	The cargo has received customs clearance at Destination Airport

Note: Refer to this article here for more Ocean-specific Tracking Update Statuses and Events.

Air Split Shipments

Whenever there is a split in the Air loads, the Tracking Update callback will have the fields given in the table below to show Split Shipment specific values.

Field Name	Description	Sample Values
Message	Tracking Update description specific to Active or Resolved split.	"Split Shipment Resolved - All pieces arrived at the stop"
Status	Indicates the split type / status.	"Resolved SPL", "Active SPL"
StopName	Stop where the Split happens.	"SIN"
Timestamp	Current time when split is identified	"2024-08-10 14:30:28 +0000 UTC"