Truckload (TL)
4 min
To update your TL load without any hassle, follow the instructions given within this document.
If you receive a server error (5xx error code), please try again a few times. It's best to wait a little longer between each retry attempt. Try at least 3-5 times before giving up, as many server issues resolve themselves quickly.
Rate Limit
1 request per second
Format Supported
JSON
Authenticated Resource
API Key
For more information on Authentication, click here.
The FourKites internal loadId that is returned during load creation should be added to the endpoint to update the load. Click on the load that you would like to update to get the FourKites Internal LoadId as shown in the image below.
The update behavior is determined by the simpleUpdate flag, which can be either true or false. Below are the scenarios for both settings.
simpleUpdate = True
With the simple update flag set to true, the update logic adheres to the following principles:
- Updating and Adding Stops:
- Scenario: If a load contains stops with stop reference IDs 1,2 and receives an update with stops 1,2,3, stops with stop reference id 1 and 2 are updated with the details provided in the request. Stop with stop reference id 3 is added additionally.
- Replacing All Stops:
- Scenario: If a load contains stops with stop reference IDs 1,2 and receives an update with stops 3,4,5, stops with stop reference id 1 and 2 are deleted, and stops 3, 4, 5 are added.
- Handling Stops Without Stop Reference IDs:
- Scenario: If a load contains stops without stop reference IDs and receives an update with stops also lacking reference IDs, the existing stops are deleted, and the stops sent in the request are created.
When simpleUpdate is set to True, the system applies straightforward updating logic. If an update includes stops with stop reference IDs matching existing stops (e.g., stops 1 and 2), those stops are updated with the new details. Any new stops (e.g., stop 3) are added. When the update provides entirely different stop reference IDs (e.g., 3, 4, 5), all existing stops are deleted, and the new ones are added. If neither the existing stops nor the update contain stop reference IDs, all stops in the load are deleted, and the new ones are created based on the request data.
simpleUpdate = False
With the simple update flag set to false, the update process follows a different set of rules:
- Updating Existing Stops and Creating Unmatched Stops:
- Scenario: If a load contains stop reference IDs 1, 2 and receives an update with stop reference IDs 1,2,3, stops 1 and 2 are updated, and stop 3 is created.
- Creating New Stops Without Existing Ones:
- Scenario: If a load contains stop reference IDs 1, 2 and receives an update with stop reference IDs 3,4, stops 3 and 4 are created.
When the simpleUpdate flag is set to False, the update process takes a more conservative approach to modifying stops. In this mode, the system focuses on updating only the existing stops and selectively creating any new ones provided in the update.
If the load already has stop reference IDs, such as 1 and 2, and the update request includes stops 1, 2, and 3, then stops 1 and 2 are updated with the new details, while stop 3, being unmatched, is created as a new stop. If the load contains stops with stop reference id 1 and 2, and the update only includes new stop reference IDs, such as 3 and 4, stops 3 and 4 are created as new stops, without affecting the existing stops 1 and 2. However, when the update lacks stop reference IDs altogether, existing stops remain unchanged—no updates, deletions, or creations occur. This approach ensures that updates respect the existing stops while allowing new stops to be added selectively when necessary.
Production
PATCH
https://api.fourkites.com/api/v1/tracking/420645495
import http.client
import json
conn = http.client.HTTPSConnection("api.fourkites.com")
payload = json.dumps({
"simpleUpdate": "True",
"trackingInfo": {
"driverPhone": "",
"truckNumber": "",
"trailerNumber": ""
},
"additionalData": {
"modeDetails": {
"shipperModes": "TL",
"carrierModes": ""
}
},
"load": {
"carrierPermalink": "support-carrier-production",
"carrierName": "Support Carrier (Production)",
"carrier": "cc79",
"haulType": [
"inbound_load"
],
"loadNumber": "TestUpdate",
"displayLoadNumber": "TestUpdate2",
"billOfLading": "billOfLading",
"bookingNumber": "bookingNumber",
"priority": "high",
"masterSequenceNumber": "1",
"masterReferenceNumber": "7328623",
"simultaneousTrackingReferenceNumber": "11223344",
"simultaneousTrackingSequenceNumber": 1,
"proNumber": "991",
"products": [
{
"lowerTemperatureThreshold": "20",
"name": "Produce",
"productId": "0123456",
"setTemperature": "28",
"timeToleranceInMinutes": "30",
"upperTemperatureThreshold": "34"
}
],
"referenceNumbers": [
"ref1",
"ref2"
],
"relayLoad": False,
"stops": [
{
"addressLine1": "500 West Madison Street",
"addressLine2": "Floor 33",
"city": "Chicago",
"country": "US",
"customer": {
"id": "789789",
"poNumbers": [
"00210123OF-203503"
],
"pointOfContact": {
"alert": False,
"email": "[email protected]",
"name": "John Doe",
"phone": "+19999999999"
}
},
"earliestAppointmentTime": "2024-10-11T01:00:00",
"earliestWantTime": "2024-10-11T01:00:00",
"externalAddressId": "100",
"latestAppointmentTime": "2024-10-11T02:00:00",
"latestWantTime": "2024-10-12T02:00:00",
"name": "FourKites HQ",
"loadingType": "drop",
"pallets": [
{
"billOfLading": "BOL123",
"number": "123444444",
"parts": [
{
"customerPartNumber": "123-FCOSS",
"orderNumber": "123",
"quantity": "1",
"shipperPartNumber": "1259924",
"weight": "41.92 LB",
"description": "Material description 1"
},
{
"customerPartNumber": "65-2333SS",
"orderNumber": "123",
"quantity": "21",
"shipperPartNumber": "59924",
"weight": "880.32 LB",
"description": "Material description 2"
},
{
"customerPartNumber": "65-24DGOSS",
"orderNumber": "123",
"quantity": "22",
"shipperPartNumber": "1924",
"weight": "922.24 LB",
"description": "Material description 3"
},
{
"customerPartNumber": "65-24S",
"orderNumber": "123",
"quantity": "15",
"shipperPartNumber": "1255524",
"weight": "628.8 LB",
"description": "Material description 4"
}
]
}
],
"postalCode": "60611",
"referenceNumbers": [
"1234567",
"2412422222",
"PalletNumber:54831396"
],
"sequence": 1,
"shipTo": "1234",
"state": "IL",
"stopReferenceId": "123",
"stopType": "pickup",
"trackingNumber": "123456789",
"unloadTimeInMinutes": 120,
"productLineItems": [
{
"productId": "0123456",
"productName": "Produce",
"productDescription": "Fresh produce shipment",
"productCategory": "Perishable",
"quantity": 100,
"measurementUnitCode": "PCE",
"netWeight": 250.5,
"weightUnit": "KGM",
"unitCost": 12.5,
"currencyCode": "USD",
"extendedCost": 1250,
"freightCost": 45,
"bestBeforeDate": "2024-10-20T08:00:00Z",
"additionalCharges": 10,
"tariffCost": 5,
"fourKitesCalculatedTariffCost": 5,
"totalLandedCost": 1310,
"countryOfOrigin": "US",
"harmonizedSystemCode": "0709999090",
"commodityTypeCode": "PRODUCE",
"htsusCode": "0709999090",
"orderNumber": "123",
"deliveryNumber": "DN-123",
"handlingUnitId": "PLT-123444444",
"barcode": "123444444",
"containerType": "pallet",
"gtin": "01234567890123",
"customerPartNumber": "123-FCOSS",
"supplierPartNumber": "1259924",
"manufacturerPartNumber": "MFG-0123456",
"itemNumber": "ITM-0123456",
"productUpc": "123444444",
"deliveryReferences": [
"DEL-REF-001"
],
"orderReferences": [
"ORD-REF-001"
],
"brandName": "FreshFarms",
"minimumTemperature": 20,
"maximumTemperature": 34,
"temperatureUnitCode": "fah",
"labelIdentifier": "LBL-0123456",
"productTrackingNumber": "123456789",
"deviceType": "RFID_TAG"
}
]
},
{
"addressLine1": "1001 E 17th Street",
"addressLine2": "",
"city": "Bloomington",
"country": "US",
"customer": {
"id": "789789",
"poNumbers": [
"00210123OF-203503"
],
"pointOfContact": {
"alert": False,
"email": "[email protected]",
"name": "John Doe",
"phone": "+19999999999"
}
},
"earliestAppointmentTime": "2024-10-11T05:00:00",
"externalAddressId": "200",
"latestAppointmentTime": "2024-10-11T06:00:00",
"name": "Assembly Hall",
"pallets": [
{
"billOfLading": "BOL123",
"number": "123444444",
"parts": [
{
"customerPartNumber": "123-FCOSS",
"orderNumber": "123",
"quantity": "1",
"shipperPartNumber": "1259924",
"weight": "41.92 LB",
"description": "Material description 1"
},
{
"customerPartNumber": "65-2333SS",
"orderNumber": "123",
"quantity": "21",
"shipperPartNumber": "59924",
"weight": "880.32 LB",
"description": "Material description 2"
},
{
"customerPartNumber": "65-24DGOSS",
"orderNumber": "123",
"quantity": "22",
"shipperPartNumber": "1924",
"weight": "922.24 LB",
"description": "Material description 3"
},
{
"customerPartNumber": "65-24S",
"orderNumber": "123",
"quantity": "15",
"shipperPartNumber": "1255524",
"weight": "628.8 LB",
"description": "Material description 4"
}
]
}
],
"postalCode": "47408",
"referenceNumbers": [
"1234567",
"2412422222",
"PalletNumber:54831396"
],
"sequence": 2,
"state": "IN",
"stopReferenceId": "9876",
"stopType": "delivery",
"trackingNumber": "123456789",
"unloadTimeInMinutes": 150,
"wantTime": "2024-10-12T13:00:00Z",
"productLineItems": [
{
"productId": "0123456",
"productName": "Produce",
"productDescription": "Fresh produce shipment",
"productCategory": "Perishable",
"quantity": 100,
"measurementUnitCode": "PCE",
"netWeight": 250.5,
"weightUnit": "KGM",
"unitCost": 12.5,
"currencyCode": "USD",
"extendedCost": 1250,
"freightCost": 45,
"additionalCharges": 10,
"tariffCost": 5,
"fourKitesCalculatedTariffCost": 5,
"totalLandedCost": 1310,
"countryOfOrigin": "US",
"harmonizedSystemCode": "0709999090",
"commodityTypeCode": "PRODUCE",
"htsusCode": "0709999090",
"orderNumber": "123",
"deliveryNumber": "DN-123",
"handlingUnitId": "PLT-123444444",
"barcode": "123444444",
"containerType": "pallet",
"gtin": "01234567890123",
"customerPartNumber": "123-FCOSS",
"supplierPartNumber": "1259924",
"manufacturerPartNumber": "MFG-0123456",
"itemNumber": "ITM-0123456",
"productUpc": "123444444",
"deliveryReferences": [
"DEL-REF-001"
],
"orderReferences": [
"ORD-REF-001"
],
"brandName": "FreshFarms",
"minimumTemperature": 20,
"maximumTemperature": 34,
"temperatureUnitCode": "fah",
"labelIdentifier": "LBL-0123456",
"productTrackingNumber": "123456789",
"deviceType": "QR_CODE"
}
]
}
],
"tags": [
"Tag1",
"Tag2",
"Tag3"
],
"trackingInfo": {
"deviceId": "12356",
"driverId": "999",
"driverPhone": "+19999999999",
"mawb": "17233144555",
"trailerNumber": "123",
"truckNumber": "456"
},
"trackingNumber": "123456789",
"truckRoutingParams": {
"height": "4.145",
"length": "14.63",
"limitedWeight": "996",
"shippedHazardousGoods": "flammable",
"trailersCount": 0,
"truckType": "truck",
"tunnelCategory": "C",
"weightPerAxle": "498",
"width": "2.438"
},
"seal": "XYZ123",
"sealStatus": "XYZ123"
}
})
headers = {
'Content-Type': 'application/json',
'apikey': 'REPLACE_KEY_VALUE'
}
conn.request("PATCH", "/api/v1/tracking/420645495", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))Staging
PATCH
https://api-staging.fourkites.com/api/v1/tracking/420645495
import http.client
import json
conn = http.client.HTTPSConnection("api-staging.fourkites.com")
payload = json.dumps({
"simpleUpdate": "True",
"trackingInfo": {
"driverPhone": "",
"truckNumber": "",
"trailerNumber": ""
},
"additionalData": {
"modeDetails": {
"shipperModes": "TL",
"carrierModes": ""
}
},
"load": {
"carrierPermalink": "support-carrier-production",
"carrierName": "Support Carrier (Production)",
"carrier": "cc79",
"haulType": [
"inbound_load"
],
"loadNumber": "TestUpdate",
"displayLoadNumber": "TestUpdate2",
"billOfLading": "billOfLading",
"bookingNumber": "bookingNumber",
"priority": "high",
"masterSequenceNumber": "1",
"masterReferenceNumber": "7328623",
"simultaneousTrackingReferenceNumber": "11223344",
"simultaneousTrackingSequenceNumber": 1,
"proNumber": "991",
"products": [
{
"lowerTemperatureThreshold": "20",
"name": "Produce",
"productId": "0123456",
"setTemperature": "28",
"timeToleranceInMinutes": "30",
"upperTemperatureThreshold": "34"
}
],
"referenceNumbers": [
"ref1",
"ref2"
],
"relayLoad": False,
"stops": [
{
"addressLine1": "500 West Madison Street",
"addressLine2": "Floor 33",
"city": "Chicago",
"country": "US",
"customer": {
"id": "789789",
"poNumbers": [
"00210123OF-203503"
],
"pointOfContact": {
"alert": False,
"email": "[email protected]",
"name": "John Doe",
"phone": "+19999999999"
}
},
"earliestAppointmentTime": "2024-10-11T01:00:00",
"earliestWantTime": "2024-10-11T01:00:00",
"externalAddressId": "100",
"latestAppointmentTime": "2024-10-11T02:00:00",
"latestWantTime": "2024-10-12T02:00:00",
"name": "FourKites HQ",
"loadingType": "drop",
"pallets": [
{
"billOfLading": "BOL123",
"number": "123444444",
"parts": [
{
"customerPartNumber": "123-FCOSS",
"orderNumber": "123",
"quantity": "1",
"shipperPartNumber": "1259924",
"weight": "41.92 LB",
"description": "Material description 1"
},
{
"customerPartNumber": "65-2333SS",
"orderNumber": "123",
"quantity": "21",
"shipperPartNumber": "59924",
"weight": "880.32 LB",
"description": "Material description 2"
},
{
"customerPartNumber": "65-24DGOSS",
"orderNumber": "123",
"quantity": "22",
"shipperPartNumber": "1924",
"weight": "922.24 LB",
"description": "Material description 3"
},
{
"customerPartNumber": "65-24S",
"orderNumber": "123",
"quantity": "15",
"shipperPartNumber": "1255524",
"weight": "628.8 LB",
"description": "Material description 4"
}
]
}
],
"postalCode": "60611",
"referenceNumbers": [
"1234567",
"2412422222",
"PalletNumber:54831396"
],
"sequence": 1,
"shipTo": "1234",
"state": "IL",
"stopReferenceId": "123",
"stopType": "pickup",
"trackingNumber": "123456789",
"unloadTimeInMinutes": 120,
"productLineItems": [
{
"productId": "0123456",
"productName": "Produce",
"productDescription": "Fresh produce shipment",
"productCategory": "Perishable",
"quantity": 100,
"measurementUnitCode": "PCE",
"netWeight": 250.5,
"weightUnit": "KGM",
"unitCost": 12.5,
"currencyCode": "USD",
"extendedCost": 1250,
"freightCost": 45,
"bestBeforeDate": "2024-10-20T08:00:00Z",
"additionalCharges": 10,
"tariffCost": 5,
"fourKitesCalculatedTariffCost": 5,
"totalLandedCost": 1310,
"countryOfOrigin": "US",
"harmonizedSystemCode": "0709999090",
"commodityTypeCode": "PRODUCE",
"htsusCode": "0709999090",
"orderNumber": "123",
"deliveryNumber": "DN-123",
"handlingUnitId": "PLT-123444444",
"barcode": "123444444",
"containerType": "pallet",
"gtin": "01234567890123",
"customerPartNumber": "123-FCOSS",
"supplierPartNumber": "1259924",
"manufacturerPartNumber": "MFG-0123456",
"itemNumber": "ITM-0123456",
"productUpc": "123444444",
"deliveryReferences": [
"DEL-REF-001"
],
"orderReferences": [
"ORD-REF-001"
],
"brandName": "FreshFarms",
"minimumTemperature": 20,
"maximumTemperature": 34,
"temperatureUnitCode": "fah",
"labelIdentifier": "LBL-0123456",
"productTrackingNumber": "123456789",
"deviceType": "RFID_TAG"
}
]
},
{
"addressLine1": "1001 E 17th Street",
"addressLine2": "",
"city": "Bloomington",
"country": "US",
"customer": {
"id": "789789",
"poNumbers": [
"00210123OF-203503"
],
"pointOfContact": {
"alert": False,
"email": "[email protected]",
"name": "John Doe",
"phone": "+19999999999"
}
},
"earliestAppointmentTime": "2024-10-11T05:00:00",
"externalAddressId": "200",
"latestAppointmentTime": "2024-10-11T06:00:00",
"name": "Assembly Hall",
"pallets": [
{
"billOfLading": "BOL123",
"number": "123444444",
"parts": [
{
"customerPartNumber": "123-FCOSS",
"orderNumber": "123",
"quantity": "1",
"shipperPartNumber": "1259924",
"weight": "41.92 LB",
"description": "Material description 1"
},
{
"customerPartNumber": "65-2333SS",
"orderNumber": "123",
"quantity": "21",
"shipperPartNumber": "59924",
"weight": "880.32 LB",
"description": "Material description 2"
},
{
"customerPartNumber": "65-24DGOSS",
"orderNumber": "123",
"quantity": "22",
"shipperPartNumber": "1924",
"weight": "922.24 LB",
"description": "Material description 3"
},
{
"customerPartNumber": "65-24S",
"orderNumber": "123",
"quantity": "15",
"shipperPartNumber": "1255524",
"weight": "628.8 LB",
"description": "Material description 4"
}
]
}
],
"postalCode": "47408",
"referenceNumbers": [
"1234567",
"2412422222",
"PalletNumber:54831396"
],
"sequence": 2,
"state": "IN",
"stopReferenceId": "9876",
"stopType": "delivery",
"trackingNumber": "123456789",
"unloadTimeInMinutes": 150,
"wantTime": "2024-10-12T13:00:00Z",
"productLineItems": [
{
"productId": "0123456",
"productName": "Produce",
"productDescription": "Fresh produce shipment",
"productCategory": "Perishable",
"quantity": 100,
"measurementUnitCode": "PCE",
"netWeight": 250.5,
"weightUnit": "KGM",
"unitCost": 12.5,
"currencyCode": "USD",
"extendedCost": 1250,
"freightCost": 45,
"additionalCharges": 10,
"tariffCost": 5,
"fourKitesCalculatedTariffCost": 5,
"totalLandedCost": 1310,
"countryOfOrigin": "US",
"harmonizedSystemCode": "0709999090",
"commodityTypeCode": "PRODUCE",
"htsusCode": "0709999090",
"orderNumber": "123",
"deliveryNumber": "DN-123",
"handlingUnitId": "PLT-123444444",
"barcode": "123444444",
"containerType": "pallet",
"gtin": "01234567890123",
"customerPartNumber": "123-FCOSS",
"supplierPartNumber": "1259924",
"manufacturerPartNumber": "MFG-0123456",
"itemNumber": "ITM-0123456",
"productUpc": "123444444",
"deliveryReferences": [
"DEL-REF-001"
],
"orderReferences": [
"ORD-REF-001"
],
"brandName": "FreshFarms",
"minimumTemperature": 20,
"maximumTemperature": 34,
"temperatureUnitCode": "fah",
"labelIdentifier": "LBL-0123456",
"productTrackingNumber": "123456789",
"deviceType": "QR_CODE"
}
]
}
],
"tags": [
"Tag1",
"Tag2",
"Tag3"
],
"trackingInfo": {
"deviceId": "12356",
"driverId": "999",
"driverPhone": "+19999999999",
"mawb": "17233144555",
"trailerNumber": "123",
"truckNumber": "456"
},
"trackingNumber": "123456789",
"truckRoutingParams": {
"height": "4.145",
"length": "14.63",
"limitedWeight": "996",
"shippedHazardousGoods": "flammable",
"trailersCount": 0,
"truckType": "truck",
"tunnelCategory": "C",
"weightPerAxle": "498",
"width": "2.438"
},
"seal": "XYZ123",
"sealStatus": "XYZ123"
}
})
headers = {
'Content-Type': 'application/json',
'apikey': 'REPLACE_KEY_VALUE'
}
conn.request("PATCH", "/api/v1/tracking/420645495", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))