Get Shipments

14 min

This API returns the paginated list of shipments. This API supports multiple filters/query parameters as described below. All of these filters/query parameters are optional and can be applied as necessary. However, createdStartDate & createdEndDate parameters are mandatory for Ocean/Intermodal loads.

Rate Limit

1 request per second

Format Supported

JSON

Authenticated Resource

API Key

For more information on Authentication, click here.

This endpoint includes shipments shared with your account by other companies on the FourKites network. Shared loads are returned alongside your own shipments and are identifiable via the shipper field in the response. This behavior is consistent across both GET /shipments and GET /shipment-details/{id}.

Get Shipments API has a record limit of returning 5500 shipments. If there are more than 5500 shipments, you will receive an Allowed number of results exceeded, Please refine your search. error around the 55th page as each page will possess a maximum of 100 shipments.

Production

GET

https://api.fourkites.com/shipments?customerId=SOME_ARRAY_VALUE&pickupStartDate=SOME_STRING_VALUE&pickupEndDate=SOME_STRING_VALUE&deliveryStartDate=SOME_STRING_VALUE&deliveryEndDate=SOME_STRING_VALUE&shipTo=SOME_ARRAY_VALUE&pickupStopName=SOME_ARRAY_VALUE&terminalStopName=SOME_ARRAY_VALUE&deliveryStopName=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&status=SOME_STRING_VALUE&orderNumber=SOME_STRING_VALUE

curl --location 'https://api.fourkites.com/shipments?customerId=SOME_ARRAY_VALUE&pickupStartDate=SOME_STRING_VALUE&pickupEndDate=SOME_STRING_VALUE&deliveryStartDate=SOME_STRING_VALUE&deliveryEndDate=SOME_STRING_VALUE&shipTo=SOME_ARRAY_VALUE&pickupStopName=SOME_ARRAY_VALUE&terminalStopName=SOME_ARRAY_VALUE&deliveryStopName=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&status=SOME_STRING_VALUE&orderNumber=SOME_STRING_VALUE' \
--header 'apikey: REPLACE_KEY_VALUE'

Staging

GET

https://api-staging.fourkites.com/shipments?customerId=SOME_ARRAY_VALUE&pickupStartDate=SOME_STRING_VALUE&pickupEndDate=SOME_STRING_VALUE&deliveryStartDate=SOME_STRING_VALUE&deliveryEndDate=SOME_STRING_VALUE&shipTo=SOME_ARRAY_VALUE&pickupStopName=SOME_ARRAY_VALUE&terminalStopName=SOME_ARRAY_VALUE&deliveryStopName=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&status=SOME_STRING_VALUE&orderNumber=SOME_STRING_VALUE

var request = URLRequest(url: URL(string: "https://api-staging.fourkites.com/shipments?customerId=SOME_ARRAY_VALUE&pickupStartDate=SOME_STRING_VALUE&pickupEndDate=SOME_STRING_VALUE&deliveryStartDate=SOME_STRING_VALUE&deliveryEndDate=SOME_STRING_VALUE&shipTo=SOME_ARRAY_VALUE&pickupStopName=SOME_ARRAY_VALUE&terminalStopName=SOME_ARRAY_VALUE&deliveryStopName=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&status=SOME_STRING_VALUE&orderNumber=SOME_STRING_VALUE")!,timeoutInterval: Double.infinity)
request.addValue("REPLACE_KEY_VALUE", forHTTPHeaderField: "apikey")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Azure - Production

GET

https://api.ng.fourkites.com/shipments?customerId=SOME_ARRAY_VALUE&pickupStartDate=SOME_STRING_VALUE&pickupEndDate=SOME_STRING_VALUE&deliveryStartDate=SOME_STRING_VALUE&deliveryEndDate=SOME_STRING_VALUE&shipTo=SOME_ARRAY_VALUE&pickupStopName=SOME_ARRAY_VALUE&terminalStopName=SOME_ARRAY_VALUE&deliveryStopName=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&status=SOME_STRING_VALUE&orderNumber=SOME_STRING_VALUE

var request = URLRequest(url: URL(string: "https://api.ng.fourkites.com/shipments?customerId=SOME_ARRAY_VALUE&pickupStartDate=SOME_STRING_VALUE&pickupEndDate=SOME_STRING_VALUE&deliveryStartDate=SOME_STRING_VALUE&deliveryEndDate=SOME_STRING_VALUE&shipTo=SOME_ARRAY_VALUE&pickupStopName=SOME_ARRAY_VALUE&terminalStopName=SOME_ARRAY_VALUE&deliveryStopName=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&status=SOME_STRING_VALUE&orderNumber=SOME_STRING_VALUE")!,timeoutInterval: Double.infinity)
request.addValue("REPLACE_KEY_VALUE", forHTTPHeaderField: "apikey")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Azure - Staging

GET

https://api-staging.ng.fourkites.com/shipments?customerId=SOME_ARRAY_VALUE&pickupStartDate=SOME_STRING_VALUE&pickupEndDate=SOME_STRING_VALUE&deliveryStartDate=SOME_STRING_VALUE&deliveryEndDate=SOME_STRING_VALUE&shipTo=SOME_ARRAY_VALUE&pickupStopName=SOME_ARRAY_VALUE&terminalStopName=SOME_ARRAY_VALUE&deliveryStopName=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&status=SOME_STRING_VALUE&orderNumber=SOME_STRING_VALUE

var request = URLRequest(url: URL(string: "https://api-staging.ng.fourkites.com/shipments?customerId=SOME_ARRAY_VALUE&pickupStartDate=SOME_STRING_VALUE&pickupEndDate=SOME_STRING_VALUE&deliveryStartDate=SOME_STRING_VALUE&deliveryEndDate=SOME_STRING_VALUE&shipTo=SOME_ARRAY_VALUE&pickupStopName=SOME_ARRAY_VALUE&terminalStopName=SOME_ARRAY_VALUE&deliveryStopName=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&status=SOME_STRING_VALUE&orderNumber=SOME_STRING_VALUE")!,timeoutInterval: Double.infinity)
request.addValue("REPLACE_KEY_VALUE", forHTTPHeaderField: "apikey")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Query Parameter Table

Name	Param Type	Format	Default	Example	Description
page	Query	Integer	1	1	Returns results associated with the given page number.
perPage	Query	Integer	10	10	The maximum results to be returned by the List API. The minimum value is 1 and the maximum value is 100.
customerId	Query	Pipe Delimited string array	NA	customer1\|customer2	Filter loads by a customer (shipper) given ID associated with a load.
pickupStartDate	Query	Date in YYYY-MM-DD	The default value is -30 days from the current date.	2020-06-18	Filter loads by their pickup appointment range. The value denotes that the loads returned should have pickup appointments greater than or equal to the pickupStartDate. The maximum supported value is +/- 90 days from the current date.
pickupEndDate	Query	Date in YYYY-MM-DD	The default value is +90 days from the current date.	2020-06-19	Filter loads by their pickup appointment range. The value denotes that the loads returned should have pickup appointments less than or equal to the pickupEndDate. The maximum supported value is +/- 90 days from the current date.
deliveryStartDate	Query	Date in YYYY-MM-DD	NA	2020-06-18	Filter loads by their delivery appointment range. The value denotes that the loads returned should have delivery appointments greater than or equal to the deliveryStartDate. It is always combined with a pickup appointment range. If we don’t pass on pickup appointment range along with deliveryStartDate, default values for pickup appointment range (pickupStartDate = -30 days from current date and pickupEndDate = +90 days from current date) will be considered.
deliveryEndDate	Query	Date in YYYY-MM-DD	NA	2020-06-19	Filter loads by their delivery appointment range. The value denotes that the loads returned should have delivery appointments lesser than or equal to the deliveryEndDate. It is always combined with a pickup appointment range. If we don’t pass on pickup appointment range along with deliveryEndDate, default values for pickup appointment range (pickupStartDate = -30 days from current date and pickupEndDate = +90 days from current date) will be considered.
shipTo	Query	Pipe Delimited string array	NA	customer1\|customer2	Filter loads by the receiver associated with a load.
pickupStopName	Query	Pipe Delimited string array	NA	stop1\|stop2	Filter loads associated with a given list of pickup stops.
terminalStopName	Query	Pipe Delimited string array	NA	stop1\|stop2	Filter loads associated with a given list of terminal stops.
deliveryStopName	Query	Pipe Delimited string array	NA	stop1\|stop2	Filter loads associated with a given list of delivery stops.
createdStartDate	Query	Date in YYYY-MM-DD	Valid range is -90 days in past.	2022-01-01	It will filter shipments with respect to created at timestamp. If invalid range is provided, timestamps will be reset and results as per -90 days to present date will be displayed.
createdEndDate	Query	Date in YYYY-MM-DD	Valid range is -90 days in past.	2022-04-30	It will filter shipments with respect to created at timestamp. If invalid range is provided, timestamps will be reset and results as per -90 days to present date will be displayed.
status	Query	String Enum; Allowed values are active, awaitingTrackingInfo, delivered and expired	Returns loads of all statuses	active	Filter loads of a given tracking status. If no value is given, loads for all statuses are returned.
loadNumber	Query	String	NA	2008604472	Load or Shipment Number. This is the same as what is shown in the FourKites Web Application

Response Attributes

Shipment

Name	Format	Default	Description
fourKitesShipmentID	String	NA	FourKites® unique identifier for a load.
loadNumber	String	NA	Load or Shipment Number. This is the same as what is shown in the FourKites® Web Application.
priority	String	NA	Indicates the priority level of the shipment. Possible values: normal, high, hot.
identifiers	Identifiers	NA	Identifiers of a load.
latestLocation	Location	NA	The last known location of a load.
SCAC	String	NA	Standard Carrier Alpha Code
fourKitesETA	Timestamp in ISO8601/RFC3339 format with timezone.	NA	ETA to the last delivery stop.
timeZone	String, conforms to IANA database	UTC	The timezone associated with the last delivery stop.
numberOfDeliveryStops	Integer	NA	Number of delivery stops without pickup/terminal stops.
remainingDistanceInMeters	Integer	NA	Remaining distance to the last delivery stop.
totalDistanceInMeters	Integer	NA	Total distance from pickup to last delivery stop.
stakeholders	Stakeholders	NA	The companies associated with a load.
status	String; Allowed values are On Track, Delayed, At Facility, Completed and Not Tracking	NA	Tracking Status of a load.
postalCode	String	NA	The postal code of the stop address.
bookingNumber	String	NA	Booking Number is the identifier issued by the carrier or shipping line to confirm a reserved shipment or container space.
billOfLading	String	NA	Bill of Lading is the identifier for the legal document issued by the carrier that acknowledges receipt of cargo and serves as a shipment record.

Identifiers

Name	Format	Default	Description
consignmentNumber	String	NA	consignment Number is a load identifier that denotes which consignment it belongs to.
consignmentSequence	Integer	NA	consignment Sequence is a load identifier specific to consignment loads that denotes the order of delivery
proNumber	String	NA	proNumber is a load Identifier for LTL loads.
purchaseOrderNumbers	String Array	NA	A list of purchase orders that the load belongs to.
referenceNumbers	String Array	NA	A list of customer given reference Numbers that the load belongs to.

Location

Name	Format	Default	Description
latitude	Float	NA	Latitude of the location the load was last found at.
longitude	Float	NA	Longitude of the location the load was last found at.
name	String	NA	Location Name as given by the tracking provider.
updatedTime	Timestamp in ISO8601/RFC3339 format with timezone.	NA	The timestamp of the associated location.
timeZone	String, conforms to	NA	The local timezone associated with the latest location.

Stakeholders

Name	Format	Default	Description
shipper	String	NA	Name of the shipper.
thirdPartyLogistics	String	NA	Name of the 3PL associated with the load.
carrier	String	NA	Name of the carrier that is transporting the load.

Stop

Name	Format	Default	Description
fourKitesStopID	String	NA	FourKites® unique identifier for a stop of a load.
stopName	String	NA	Name of the stop as given during load creation.
city	String	NA	City of the stop.
state	String	NA	State of the stop.
country	String	NA	Country of the stop.
externalAddressID	String	NA	It is the unique identifier of the address in FourKites. This ID is sent in place of address information.
latitude	Float	NA	Latitude of the stop.
longitude	Float	NA	Longitude of the stop.
schedule	Schedule	NA	The time schedule of the load for the given stop.
timeZone	String, conforms to IANA database	UTC	The local timezone associated with the stop’s location.
sequence	Integer	NA	The sequence of the stops as given during load creation.
status	String	NA	The tracking status to the stop.
customer	Customer	NA	The Customer to which the load is delivered to.
stopType	Stop Type	NA	The action performed at the stop. The action is mode-specific.
arrivalTime	Timestamp in ISO8601/RFC3339 format with timezone.	NA	The latest arrival time at the stop.
departureTime	Timestamp in ISO8601/RFC3339 format with timezone.	NA	The latest departure time at the stop.
pallets	Array	NA	It indicates the shipper, customer part number , quantity, weight of the pallet and description which helps in identifying the exact product type. Example: :::BlockQuote
[ { "number": "1", "parts": [ { "shipperPartNumber": "100105317", "customerPartNumber": "", "quantity": "45000.0 LB", "weight": "45000.000 LB", "description": "CITRIC ACID 540 LIQ BLK" } ] } ]
:::
postalCode	String	NA	The postal code of the stop address.

Schedule

Name	Format	Default	Description
appointmentTime	Timestamp in ISO8601/RFC3339 format with timezone.	NA	The schedule time of arrival at the stop.
appointmentWindowStart	Timestamp in ISO8601/RFC3339 format with timezone.	NA	The earliest appointment time at the stop.
appointmentWindowEnd	Timestamp in ISO8601/RFC3339 format with timezone.	NA	The latest appointment time at the stop.
wantTime	Timestamp in ISO8601/RFC3339 format with timezone.	NA	The latest time to be at the stop.

Customer

Name	Format	Default	Description
id	String	NA	Shipper given id for their customers.
name	String	NA	Shipper given name for their customers.

Stop Type

Following is the list of available stop types based on the mode of transport.

Truck and Rail Loads:

PICKUP

DELIVERY

TERMINAL

Ocean Loads:

PORT_OF_LOADING

PORT_OF_DISCHARGE

TRANS_SHIPMENT_PORT

EMPTY_PICKUP_LOCATION

PLACE_OF_RECEIPT

DELIVERY

EMPTY_RETURN_LOCATION

Air Loads:

ORIGIN_AIRPORT

DESTINATION_AIRPORT

HUB_AIRPORT