The Create Load API supplies a single API to seed data into all 3 FourKites products. Below are the 3 objects which can be created via a single message:

If the FourKites Core Tracking platform is used, then loads created in Core Track will automatically integrate into Dynamic Yard, creating pending deliveries. This allows for the usage of a single TMS integration with FourKites at the Core Track level. From there, references, trailer numbers, appointments, and other information already sent to Core Track will automatically populate in Dynamic Yard.

The following API specification is only if Core Track or Appointment Manager is not used. If the Core Track platform is used, then no separate load or delivery integration needs to be built.

The Create / Update Load API uses API key to authenticate requests. This key can be generated from the FourKites Developer Portal. Each request requires an API key in order to authenticate:

Production:

Staging:

Fourkites APIs have rate limits that cap the number of requests that can be successfully made. If you exceed the specified rate limit, your request will be throttled, and you will receive HTTP 429 Too Many Requests response from the API. The rate limits will be applied per apikey and the default rate limit is 60 requests per minute. Please contact your Customer Success Manager to request an increase in the rate limit.

Below are the response headers related to the rate limit, that can be used for retries. For example, in cases where there are intermittent spikes in request rate, an exponential retry can be implemented.

FourKites uses conventional HTTP response codes to indicate the success or failure of an API request.

Each request has specific errors that are detailed throughout the documentation. This document contains a general description of errors that could occur across all request types and a description of the common error response format. There are two errors formats which denote generic/default and custom errors which can be resource or action-specific.

Default errors contain a message in the body which provides information about the nature of the error:

Custom errors provide an object with different keys containing information about the error. Custom error codes and the details in the errorDetails field are not directly related to a HTTP Status Code as it can mean request or resource specific errors as described below

The following table outlines different custom errors:

There are 2 types of updates which can be performed on FourKites loads:

Full Update: The entire payload representation is sent again with the latest information on the load. FourKites will detect any field(s) which have changed and run it as an update. If certain field(s) have not changed then they will not be altered

Partial Update: Only the field(s) which have changed are sent in the message. This allows a more targeted approach to updates but requires the source system to know which fields have been changed.

The full update is invoked using a query parameter simpleUpdate=true. Leaving this parameter off of the request will default to a partial update.

The following field definitions outline the most common and useful fields for creating loads for use in Appointment Manager and Dynamic Yard. For additional field-level specifications which may be outside this list please visit the "Create Load" section of the FourKites Developer Portal.

FourKites supports storing limited information about the pallets or freight associated with a shipment. The pallet information can be included as part of the stop object (so it can be unique for pickup and/or delivery). The structure is as follows.

Inside the parts array is an object representing each individual pallet. The field definitions below correspond to each individual pallet. Within the pallet object, each field is considered optional. This means that you can only include quantity and weight, or any other combination of fields within the object.