Dispatcher Update - Asynchronous (All Key-Value)
4 min
This document contains a sample payload with all the relevant parameters and a request parameter description for all the available keys.
Format Supported
JSON
Authenticated Resource
API Key
When providing stop identifiers, such as PostalCode, StopSequence, StopId, StopReferenceId, or StopReferenceNumber for stop-level updates (e.g., X3, AF, X1, D1, etc.), it is essential that each identifier is unique to a specific stop.
If an identifier is used for more than one stop, the update will not be processed successfully.
For more information on Authentication, click here.
Production
POST
https://api.fourkites.com/load/update/dispatcher-api/async
curl --location 'https://api.fourkites.com/load/update/dispatcher-api/async' \
--header 'Content-Type: application/json' \
--header 'apikey: testkey' \
--data '{
"updates": [
{
"timeZone": "UTC",
"billToCode": "Shipper unique id",
"identifierKeys": [
{
"identifier": "Load reference #1",
"rawIdentifier": "Carrier format - Load reference #1",
"identifierType": "Load reference identifier type in FourKites or Carrier company"
},
{
"identifier": "Load reference #2",
"rawIdentifier": "Carrier format - Load reference #2",
"identifierType": "Load reference identifier type in FourKites or Carrier company"
},
{
"identifier": "Load reference #3",
"rawIdentifier": "Carrier format - Load reference #3",
"identifierType": "Load reference identifier type in FourKites or Carrier company"
},
{
"identifier": "Load reference #4",
"rawIdentifier": "Carrier format - Load reference #4",
"identifierType": "Load reference identifier type in FourKites or Carrier company"
}
],
"assignmentUpdate": {
"operatingCarrierScac": "Operating Carrier SCAC ID",
"truckNumber": "Truck Number as in the GPS/ELD portal",
"trailerNumber": "Trailer Number as in the GPS/ELD portal",
"deviceId": "Device Id as in the GPS/ELD portal",
"driverPhone": "Driver Phone Number with the Country Code",
"driverName": "Driver Name",
"driverLicenseNumber": "Driver Truck License Number",
"railEquipmentInitials": "4-character rail equipment prefix",
"railEquipmentNumber": "6-digit rail equipment number",
"wagonNumber": "Wagon Number",
"oceanContainer": "Ocean Containter",
"loadMode": "Mode of the load to be assigned"
},
"stopUpdate": {
"appointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"earliestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"latestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"stopType": "pickup",
"stopSequence": 1,
"stopReferenceId": "stopReferenceId",
"postalCode": "postalCode",
"statusCode": "statusCodestop",
"statusDescription": "statusDescriptionstop",
"statusReasonCode": "statusReasonCodestop",
"eventTimeStamp": "YYYY-MM-DDTHH:MM:SSZ",
"earliestAppointmentDateOnly": "YYYY-MM-DD",
"earliestAppointmentTimeOnly": "HH:MM:SS",
"latestAppointmentDateOnly": "YYYY-MM-DD",
"latestAppointmentTimeOnly": "HH:MM:SS",
"modeType": [
"modeType generally specified as '\''intermodal'\'' to update the terminalStops for load"
],
"terminalStops": [
{
"appointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"earliestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"latestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"stopType": "originTerminal",
"transportationMode": "transportationMode",
"stopSequence": 1,
"stopReferenceId": "stopReferenceId",
"name": "stopName",
"city": "stopCity",
"state": "stopState",
"country": "stopCountry",
"latitude": "47.1667",
"longitude": "-2.1667"
},
{
"appointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"earliestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"latestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"stopType": "destinationTerminal",
"transportationMode": "transportationMode",
"stopSequence": 2,
"stopReferenceId": "stopReferenceId",
"name": "stopName",
"city": "stopCity",
"state": "stopState",
"country": "stopCountry",
"latitude": "47.1667",
"longitude": "-2.1667"
}
]
},
"loadUpdate": [
{
"locationUpdate": {
"latitude": "42.42",
"longitude": "-87.622003",
"locatedAt": "YYYY-MM-DDTHH:MM:SSZ",
"city": "Location City",
"state": "Location State code",
"deliveredAt": "YYYY-MM-DDTHH:MM:SSZ"
},
"etaUpdate": {
"estimatedArrivalAtDestination": "YYYY-MM-DDTHH:MM:SSZ",
"estimatedArrivalAtDestinationDateOnly": "YYYY-MM-DD"
},
"temperatureUpdate": {
"temperature": "0.2",
"sensorName": "sensorName",
"temperatureUnit": "C",
"temperatureCheckCallTime": "YYYY-MM-DDTHH:MM:SSZ",
"temperatureTimestamp": "YYYY-MM-DDTHH:MM:SSZ"
},
"loadInfoUpdate": {
"tags": [
"tags"
],
"updatableProNumber": "updatableProNumber",
"updatableCarrierReferenceNumber": "updatableCarrierReferenceNumber",
"brokeredLoad": false,
"relayLoad": true,
"simultaneousTrackingReferenceNumber": "simultaneousTrackingReferenceNumberloadinfo",
"endPoint": "endPoint",
"startPoint": "startPoint",
"startTime": "startTime",
"forceStart": true,
"stopTracking": "stopTracking",
"weight": "weight",
"weightUnit": "weightUnit",
"freightCharges": "freightCharges",
"freightChargeUnit": "freightChargeUnit",
"quantity": "quantity",
"simultaneousTrackingSequenceNumber": 1
},
"eventUpdate": {
"modeType": [
"ftl"
],
"statusCode": "statusCodeevent",
"statusDescription": "statusDescriptionevent",
"statusReasonCode": "statusReasonCodeevent",
"eventTimeStamp": "YYYY-MM-DDTHH:MM:SSZ",
"ecta": {
"ecta": "ecta"
},
"city": "Event City Code",
"state": "Event state code",
"country": "Event Country code",
"pickupTime": "YYYY-MM-DDTHH:MM:SSZ",
"deliveryTime": "YYYY-MM-DDTHH:MM:SSZ",
"delivered": false,
"deliveredAt": "YYYY-MM-DDTHH:MM:SSZ",
"oceanDataHash": {
"city": "City",
"state": "State code",
"country": "Country Code",
"event_timezone": "UTC",
"event_source": "dispatcher_async",
"event_date_time": "YYYY-MM-DDTHH:MM:SSZ",
"ocean_container_number": "ocean_container_number",
"update_action": "update_action"
},
"vesselLocation": "vesselLocation",
"railEventCode": "railEventCode",
"shipmentStatusIndicator": "shipmentStatusIndicator",
"shipmentStatus": "shipmentStatus",
"failedLoads": "failedLoads",
"airDataHash": {
"quantity": "1"
}
},
"additionalData": {
"simultaneousTrackingReferenceNumber": "simultaneousTrackingReferenceNumberadditional"
}
}
]
}
]
}'Staging
POST
https://api-staging.fourkites.com/load/update/dispatcher-api/async
curl --location 'https://api-staging.fourkites.com/load/update/dispatcher-api/async' \
--header 'Content-Type: application/json' \
--header 'apikey: testkey' \
--data '{
"updates": [
{
"timeZone": "UTC",
"billToCode": "Shipper unique id",
"identifierKeys": [
{
"identifier": "Load reference #1",
"rawIdentifier": "Carrier format - Load reference #1",
"identifierType": "Load reference identifier type in FourKites or Carrier company"
},
{
"identifier": "Load reference #2",
"rawIdentifier": "Carrier format - Load reference #2",
"identifierType": "Load reference identifier type in FourKites or Carrier company"
},
{
"identifier": "Load reference #3",
"rawIdentifier": "Carrier format - Load reference #3",
"identifierType": "Load reference identifier type in FourKites or Carrier company"
},
{
"identifier": "Load reference #4",
"rawIdentifier": "Carrier format - Load reference #4",
"identifierType": "Load reference identifier type in FourKites or Carrier company"
}
],
"assignmentUpdate": {
"operatingCarrierScac": "Operating Carrier SCAC ID",
"truckNumber": "Truck Number as in the GPS/ELD portal",
"trailerNumber": "Trailer Number as in the GPS/ELD portal",
"deviceId": "Device Id as in the GPS/ELD portal",
"driverPhone": "Driver Phone Number with the Country Code",
"driverName": "Driver Name",
"driverLicenseNumber": "Driver Truck License Number",
"railEquipmentInitials": "4-character rail equipment prefix",
"railEquipmentNumber": "6-digit rail equipment number",
"wagonNumber": "Wagon Number",
"oceanContainer": "Ocean Containter",
"loadMode": "Mode of the load to be assigned"
},
"stopUpdate": {
"appointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"earliestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"latestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"stopType": "pickup",
"stopSequence": 1,
"stopReferenceId": "stopReferenceId",
"postalCode": "postalCode",
"statusCode": "statusCodestop",
"statusDescription": "statusDescriptionstop",
"statusReasonCode": "statusReasonCodestop",
"eventTimeStamp": "YYYY-MM-DDTHH:MM:SSZ",
"earliestAppointmentDateOnly": "YYYY-MM-DD",
"earliestAppointmentTimeOnly": "HH:MM:SS",
"latestAppointmentDateOnly": "YYYY-MM-DD",
"latestAppointmentTimeOnly": "HH:MM:SS",
"modeType": [
"modeType generally specified as '\''intermodal'\'' to update the terminalStops for load"
],
"terminalStops": [
{
"appointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"earliestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"latestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"stopType": "originTerminal",
"transportationMode": "transportationMode",
"stopSequence": 1,
"stopReferenceId": "stopReferenceId",
"name": "stopName",
"city": "stopCity",
"state": "stopState",
"country": "stopCountry",
"latitude": "47.1667",
"longitude": "-2.1667"
},
{
"appointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"earliestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"latestAppointmentTime": "YYYY-MM-DDTHH:MM:SSZ",
"stopType": "destinationTerminal",
"transportationMode": "transportationMode",
"stopSequence": 2,
"stopReferenceId": "stopReferenceId",
"name": "stopName",
"city": "stopCity",
"state": "stopState",
"country": "stopCountry",
"latitude": "47.1667",
"longitude": "-2.1667"
}
]
},
"loadUpdate": [
{
"locationUpdate": {
"latitude": "42.42",
"longitude": "-87.622003",
"locatedAt": "YYYY-MM-DDTHH:MM:SSZ",
"city": "Location City",
"state": "Location State code",
"deliveredAt": "YYYY-MM-DDTHH:MM:SSZ"
},
"etaUpdate": {
"estimatedArrivalAtDestination": "YYYY-MM-DDTHH:MM:SSZ",
"estimatedArrivalAtDestinationDateOnly": "YYYY-MM-DD"
},
"temperatureUpdate": {
"temperature": "0.2",
"sensorName": "sensorName",
"temperatureUnit": "C",
"temperatureCheckCallTime": "YYYY-MM-DDTHH:MM:SSZ",
"temperatureTimestamp": "YYYY-MM-DDTHH:MM:SSZ"
},
"loadInfoUpdate": {
"tags": [
"tags"
],
"updatableProNumber": "updatableProNumber",
"updatableCarrierReferenceNumber": "updatableCarrierReferenceNumber",
"brokeredLoad": false,
"relayLoad": true,
"simultaneousTrackingReferenceNumber": "simultaneousTrackingReferenceNumberloadinfo",
"endPoint": "endPoint",
"startPoint": "startPoint",
"startTime": "startTime",
"forceStart": true,
"stopTracking": "stopTracking",
"weight": "weight",
"weightUnit": "weightUnit",
"freightCharges": "freightCharges",
"freightChargeUnit": "freightChargeUnit",
"quantity": "quantity",
"simultaneousTrackingSequenceNumber": 1
},
"eventUpdate": {
"modeType": [
"ftl"
],
"statusCode": "statusCodeevent",
"statusDescription": "statusDescriptionevent",
"statusReasonCode": "statusReasonCodeevent",
"eventTimeStamp": "YYYY-MM-DDTHH:MM:SSZ",
"ecta": {
"ecta": "ecta"
},
"city": "Event City Code",
"state": "Event state code",
"country": "Event Country code",
"pickupTime": "YYYY-MM-DDTHH:MM:SSZ",
"deliveryTime": "YYYY-MM-DDTHH:MM:SSZ",
"delivered": false,
"deliveredAt": "YYYY-MM-DDTHH:MM:SSZ",
"oceanDataHash": {
"city": "City",
"state": "State code",
"country": "Country Code",
"event_timezone": "UTC",
"event_source": "dispatcher_async",
"event_date_time": "YYYY-MM-DDTHH:MM:SSZ",
"ocean_container_number": "ocean_container_number",
"update_action": "update_action"
},
"vesselLocation": "vesselLocation",
"railEventCode": "railEventCode",
"shipmentStatusIndicator": "shipmentStatusIndicator",
"shipmentStatus": "shipmentStatus",
"failedLoads": "failedLoads",
"airDataHash": {
"quantity": "1"
}
},
"additionalData": {
"simultaneousTrackingReferenceNumber": "simultaneousTrackingReferenceNumberadditional"
}
}
]
}
]
}'