Easy Load Create (Ocean)
5 min
Ocean Booking/Easy Load Create API or Reference Based Load Creation API will allow users to create loads based on the reference numbers such as Booking Number, Bill of Lading, and/or container number.
⚠️ Important Update:
The Pallets structure is being deprecated. Please transition to for product details. Learn more
Note: This documentation provides load mode-specific API payloads for this transportation type. For a comprehensive reference of all available API parameters that can be applied to these payloads, including parameters across all load modes, please refer to the Create Shipment / Update Shipment documentation.
This API is called after the carrier has accepted the tender for the load. FourKites does not limit customers from creating more than one load with the same load number or PRO number -- creation of more than one load with the same load or PRO number will cause duplication of loads, which will end up affecting the tracking performance. Customers are advised to handle this on their side. To learn more about Idempotency Protection, refer here.
Rate Limit
1 request per second
Format Supported
JSON
Authenticated Resource
Users can make use of their application login credentials (Username and Password) as the means of authenticating (Basic Auth).
For more information on Authentication, click here.
If you are sending 'c_id' as the trackingReferenceIdentifier, you will have to share pickup & delivery parameters as well for better Tracking Quality.
Production
POST
https://booking-api.fourkites.com/api/v1/add_references
curl --location --request POST 'https://booking-api.fourkites.com/api/v1/add_references' \
--header 'Authorization: Basic cmFqa2lyYW4ubWFub2hhcmFuQGZvdXJraXRlcy5jb206UmFqa2lyYW5tMg==' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 880723,
"trackingReferenceIdentifier": "c_id",
"trackingReferenceNumber": "reference_number",
"shipperPermalink": "shipper_perma_link",
"carrierScac": "SCAC",
"operatingCarrierScac": "",
"consignmentReference": "",
"consignmentSequence": null,
"containerNumber": "",
"carrierPermalink": "",
"tags": "",
"loadNumber": "Load_Number",
"loadReferences": "",
"autoCreatePickup": "",
"autoCreateDelivery": "A",
"portOfDischarge": {
"wantTime": "2024-12-20T11:36:51Z",
"estimatedArrivalTime": "2025-03-02T11:36:51Z"
},
"placeOfDelivery": {
"estimatedArrivalTime": "2025-03-04T11:36:51Z"
},
"sku": [
{
"parts": [
{
"shipperPartNumber": "Sample part",
"customerPartNumber": "Sample",
"quantity": "129",
"weight": "100"
},
{
"shipperPartNumber": "Sample part 2",
"customerPartNumber": "Sample 2",
"quantity": "100",
"weight": "299 KG"
}
]
}
],
"productLineItems": [
{
"productId": "0123456",
"productName": "Ocean Freight Item",
"productDescription": "Ocean shipment item",
"productCategory": "General Freight",
"quantity": 129,
"measurementUnitCode": "PCE",
"netWeight": 100,
"weightUnit": "KGM",
"unitCost": 25.0,
"currencyCode": "USD",
"extendedCost": 625.00,
"freightCost": 20.00,
"additionalCharges": 5.00,
"tariffCost": 2.50,
"fourKitesCalculatedTariffCost": 2.50,
"totalLandedCost": 655.00,
"countryOfOrigin": "US",
"harmonizedSystemCode": "8471499000",
"commodityTypeCode": "OCEAN_FREIGHT",
"htsusCode": "8471499000",
"orderNumber": "Load_Number",
"deliveryNumber": "DN-Sample",
"handlingUnitId": "Sample part",
"barcode": "Sample",
"containerType": "pallet",
"gtin": "00012345678905",
"customerPartNumber": "Sample",
"supplierPartNumber": "Sample part",
"manufacturerPartNumber": "MFG-Sample",
"itemNumber": "ITM-Sample",
"productUpc": "012345678905",
"deliveryReferences": ["reference_number"],
"orderReferences": ["Load_Number"],
"brandName": "Generic Ocean Freight Co",
"minimumTemperature": 0,
"maximumTemperature": 0,
"temperatureUnitCode": "cel",
"labelIdentifier": "LBL-Sample",
"productTrackingNumber": "reference_number",
"deviceType": "RFID_TAG"
}
],
"pickup": {
"addressLine": "",
"location": "",
"city": "",
"state": "",
"country": "",
"latitude": "",
"longitude": "",
"locationId": "",
"arrivalTime": "",
"earliestArrivalTime": "",
"latestArrivalTime": "",
"wantTime": "",
"earliestWantTime": "",
"latestWantTime": "",
"postalCode": ""
},
"delivery": {
"addressLine": "",
"location": "",
"city": "",
"state": "",
"country": "",
"latitude": "",
"longitude": "",
"locationId": "",
"arrivalTime": "",
"earliestArrivalTime": "",
"latestArrivalTime": "",
"wantTime": "",
"earliestWantTime": "",
"latestWantTime": "",
"postalCode": ""
}
}'Staging
POST
https://booking-api-staging.fourkites.com/api/v1/add_references
curl --location --request POST 'https://booking-api-staging.fourkites.com/api/v1/add_references' \
--header 'Authorization: Basic cmFqa2lyYW4ubWFub2hhcmFuQGZvdXJraXRlcy5jb206UmFqa2lyYW5tMg==' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 880723,
"trackingReferenceIdentifier": "c_id",
"trackingReferenceNumber": "reference_number",
"shipperPermalink": "shipper_perma_link",
"carrierScac": "SCAC",
"operatingCarrierScac": "",
"consignmentReference": "",
"consignmentSequence": null,
"containerNumber": "",
"carrierPermalink": "",
"tags": "",
"loadNumber": "Load_Number",
"loadReferences": "",
"autoCreatePickup": "",
"autoCreateDelivery": "A",
"portOfDischarge": {
"wantTime": "2024-12-20T11:36:51Z",
"estimatedArrivalTime": "2025-03-02T11:36:51Z"
},
"placeOfDelivery": {
"estimatedArrivalTime": "2025-03-04T11:36:51Z"
},
"pallets": [
{
"parts": [
{
"shipperPartNumber": "Sample part",
"customerPartNumber": "Sample",
"quantity": "129",
"weight": "100"
},
{
"shipperPartNumber": "Sample part 2",
"customerPartNumber": "Sample 2",
"quantity": "100",
"weight": "299 KG"
}
]
}
],
"productLineItems": [
{
"productId": "0123456",
"productName": "Ocean Freight Item",
"productDescription": "Ocean shipment item",
"productCategory": "General Freight",
"quantity": 129,
"measurementUnitCode": "PCE",
"netWeight": 100,
"weightUnit": "KGM",
"unitCost": 25.0,
"currencyCode": "USD",
"extendedCost": 625.00,
"freightCost": 20.00,
"additionalCharges": 5.00,
"tariffCost": 2.50,
"fourKitesCalculatedTariffCost": 2.50,
"totalLandedCost": 655.00,
"countryOfOrigin": "US",
"harmonizedSystemCode": "8471499000",
"commodityTypeCode": "OCEAN_FREIGHT",
"htsusCode": "8471499000",
"orderNumber": "Load_Number",
"deliveryNumber": "DN-Sample",
"handlingUnitId": "Sample part",
"barcode": "Sample",
"containerType": "pallet",
"gtin": "00012345678905",
"customerPartNumber": "Sample",
"supplierPartNumber": "Sample part",
"manufacturerPartNumber": "MFG-Sample",
"itemNumber": "ITM-Sample",
"productUpc": "012345678905",
"deliveryReferences": ["reference_number"],
"orderReferences": ["Load_Number"],
"brandName": "Generic Ocean Freight Co",
"minimumTemperature": 0,
"maximumTemperature": 0,
"temperatureUnitCode": "cel",
"labelIdentifier": "LBL-Sample",
"productTrackingNumber": "reference_number",
"deviceType": "QR_CODE"
}
],
"pickup": {
"addressLine": "",
"location": "",
"city": "",
"state": "",
"country": "",
"latitude": "",
"longitude": "",
"locationId": "",
"arrivalTime": "",
"earliestArrivalTime": "",
"latestArrivalTime": "",
"wantTime": "",
"earliestWantTime": "",
"latestWantTime": "",
"postalCode": ""
},
"delivery": {
"addressLine": "",
"location": "",
"city": "",
"state": "",
"country": "",
"latitude": "",
"longitude": "",
"locationId": "",
"arrivalTime": "",
"earliestArrivalTime": "",
"latestArrivalTime": "",
"wantTime": "",
"earliestWantTime": "",
"latestWantTime": "",
"postalCode": ""
}
}'