Request Attributes - All Load Modes

operatingCarrierScac

Object

All



SCAC or code of the operating carrier if setting up managing/operating carrier

O

modeDetails

Object

All



It contains the mode information about the load that we create.

O

shipperModes

String

All

Valid values: "TL", "LTL", "RAIL", "OCEAN", "PARCEL"

It defines the mode of the load.

O

carrierModes

String

All

Valid values: "TL", "LTL", "RAIL", "OCEAN", "PARCEL"

It defines the mode of the load.

O

load

Object

All



It is the parent object for the load. Place the load attributes inside this object.

M

loadNumber

String

All



It is the unique load identifier from shipper's system. The load Number or BOL is an important piece of information used to link the load with truck information received from the Carrier's TMS.

M

billOfLading

String

TL,LTL,Parcel,Rail,Ocean



It indicates the bill of lading associated with the Ocean load.

O

bookingNumber

String

Ocean



It indicates the shipping line's booking number

O

carrierPermalink

String

All



It is the unique identifier for the carrier in the FK platform.

O

carrierName

String

All



It is the name of the carrier in the FK platform.

O

carrier

String

All



It is the SCAC or Service Provider ID of the carrier assigned to the load. The carrier should have approved sharing of their telematics data on FourKites® for the customer.

M

shipper

String

All



It is the unique FourKites ID of the shipper.

M for 3 PL customers

addressCreationSource

String

All



It indicates the source of address creation such as shipper, carrier, via file or via location API.

O

transitDays

Integer

All



It indicates the number of days under transit for a load.

O

masterReferenceNumber

String

TL,LTL,Parcel,Rail,Ocean



It indicates a common reference number across a group of consignment loads in order to group them. For example, consignmentReferenceNumber: “XAF-BATCH-1”

CM

simulaneousTrackingReferenceNumber

String

TL



It indicates a common reference number across a group of simultaneous loads in order to group them. For example, simultaneousTrackingReferenceNumber: “E900018290”

CM

masterSequenceNumber

String

TL,LTL,Parcel,Rail,Ocean



It is the unique sequence number that represents the leg of the trip used for Consignment Pooling.

O

proNumber

String

All



This is a number that is created usually after pickup or at pickup for LTL loads.

CM for LTL loads

trackingNumber

String

All



It is for parcel tracking only; any tracking number provided by the carrier or other entities.

O

seal

String

All



It is the seal number that identifies the seal on the load.

O

sealStatus

String

All



It is the seal status that represents the status of the seal on the load.

O

priority

String

All

Valid values: ‘normal’, ‘high’ and ‘hot’. Defaults to normal. Setting the 'Priority' as 'hot' will mark the load as 'Hot' load.

It indicates whether a load is of normal or high priority. If priority is set as ‘hot’, the load will be marked as ‘Hot’.

O

tags

Array

All

A single tag can't exceed 50 characters. Even though we don’t have restrictions on the number of tags, it is advisable to keep total characters of all tags within the count of 255.

It is the list of tags or labels to be assigned to a load. Loads can be filtered in FourKites® using tags. It is used for assigning categories for the load.

CM

referenceNumbers

Array

All



It is the list of load level reference numbers associated with a load.

CM

relayLoad

Boolean

TL

Valid values: true or false. Defaults to false.

It indicates whether the load is relay or team load.

CM

haulType

Array

TL,LTL,Parcel

Valid values: "inbound_load", "outbound_load", "short_haul", "round_trip", "brokered_load", "non-brokered_load", "inbound_load", "outbound_load", travel_ban_warnings"

It indicates whether the load is an inbound or an outbound load.

O

stops

Array of objects

All



It is the list of stops for the load.

M

stopReferenceId

String

TL,LTL,Parcel,Rail,Ocean



It is the unique identifier of the stop from the customer's system. This populates the "Reference #" field on the stop and is used to indicate which stop an update is applied to.

CM

shipTo

String

TL,LTL,Parcel,Rail,Ocean



It is the ship to location ID associated with the stop. The shipTo values associated with pickup stops can be filtered using the "Ship From" filter.

CM

stopType

String

All

Valid values: "pickup", "delivery", "transfer", "portOfLoading", "transshipmentPort", "portOfDischarge". There should be at least one pickup and delivery stop or one transfer (terminal) and one delivery. For ocean loads, there should be at least one portOfLoading and one portOfDischarge stop.

It defines the function of the stop.

M

timeInUtc

Boolean

All

Indicates whether the appointment times sent in the message are in UTC. By default, FourKites assumes the times are in the local time of the stop



O

trackingNumber

String

TL,LTL,Parcel,Rail,Ocean



It is for parcel tracking only. any tracking number provided by the carrier or other entities. The stop level trackingNumber field is mainly used for Split Shipments. Each unique TrackingNumber will have a separate entry. Hence, iterate through the entire response to create the Child shipment.

O

externalAddressId

String

Ocean,Air

UNLOCODE is preferred for port stop creation in the FK platform.

It is the unique identifier of the address in FourKites. This ID is sent in place of address information.

O

name

String

TL,LTL,Parcel,Rail



It is the name of the stop.

M

loadingType

String

TL,LTL,Parcel,Rail,Ocean



Indicates whether the load or shipment is Live or Drop. Valid values : "live" or "drop"

O

addressLine1

String

TL,LTL,Parcel,Rail



It indicates the first line of the stop's address.

M

addressLine2

String

TL,LTL,Parcel,Rail



It indicates the second line of the stop's address.

O

city

String

TL,LTL,Parcel,Rail

When we are not able to match a port with UNLOCODE, we will use city and country to find the port in the platform for port stop creation. Right now we have a restriction to pass state name when the stop doesn't have external AddressId and we match the port with only city & country.

It indicates the name of the city.

M

state

String

TL,LTL,Parcel,Rail

It is the 2 character State Code for US & Canada and 3 Character State Code for Mexico.

it indicates the 2 character state code for US & Canada and 3 Character state code for Mexico.

M

postalCode

String

TL,LTL,Parcel,Rail



It indicates the valid postal code for the stop.

O

country

String

TL,LTL,Parcel,Rail

It is the 2 digit country code. When we are not able to match a port with UNLOCODE, we will use city and country to find the port in the platform for port stop creation. Right now, we have a restriction to pass the state name when the stop doesn't have external AddressId and we want to match the port with only city & country.

It indicates the valid country code.

O

latitude

String

TL,LTL,Parcel,Rail

It is formatted to decimal degrees.The only accepted format of lat/long by FourKites® is the "Decimal Degrees" format. For example: 41.8781 (lat), -87.6298 (long).

It indicates the latitude of the stop's location.

O

longitude

String

TL,LTL,Parcel,Rail

It is formatted to decimal degrees.The only accepted format of lat/long by FourKites® is the "Decimal Degrees" format. For example: 41.8781 (lat), -87.6298 (long).

It indicates the longitude of the stop's location.

O

timezoneOffset

Integer

All

It is sent in seconds from UTC.

It indicates the UTC offset for the stop's timezone in seconds. If it is not provided, FourKites® will determine the timezone. The timezone Offset value may differ due to daylight savings. Example: The offset (-14400) matches with AST for any date from November till March, and matches with EDT for other dates (due to daylight saving switches). Recommendation: Customers should give the right timezone.

O

geofenceRadius

String

TL,LTL,Parcel



It indicates the geofence radius to be used to detect arrival and departure at this stop in meters.

O

geofencePoints

Array of objects and string

TL,LTL,Parcel



It indicates the list of lat/long coordinates of the corners of the polygon geofence around the stop to be used for detecting arrival.

O

appointmentTime

String

All

ISO 8601 format. Appointment times cannot be more than 4 days in the past from the current time.

It indicates the scheduled appointment time at the stop in the stop's local timezone in ISO 8601 format. Note: To maintain existing data during an In-Transit Load Update, you must exclude the specific field from your payload entirely. Including a field with a null value is interpreted as an intentional command to clear or delete the current information. This distinction is critical for appointment windows; passing null will collapse a time range by stripping the stored values.

M

earliestAppointmentTime

String

All

ISO 8601 format. If the earliestAppointmentTime is sent, then the latestAppointmentTime must also be sent.

It indicates the earliest scheduled arrival time at the stop in the stop's local timezone in ISO 8601 format. Note: To maintain existing data during an In-Transit Load Update, you must exclude the specific field from your payload entirely. Including a field with a null value is interpreted as an intentional command to clear or delete the current information. This distinction is critical for appointment windows; passing null will collapse a time range by stripping the stored values.

M

latestAppointmentTime

String

All

ISO 8601 format. If the latestAppointmentTime is sent, then the earliestAppointmentTime must also be sent. latestAppointmentTime should be greater than or equal to earliestAppointmentTime.

It indicates the latest scheduled arrival time at the stop in the stop's local timezone in ISO 8601 format. Note: To maintain existing data during an In-Transit Load Update, you must exclude the specific field from your payload entirely. Including a field with a null value is interpreted as an intentional command to clear or delete the current information. This distinction is critical for appointment windows; passing null will collapse a time range by stripping the stored values.

M

estimatedDepartureTime

String

Ocean

ISO 8601 format.

It indicates the time by which the load has departed from the port of loading in stop’s local timezone in ISO 8601 format.

CM

wantTime

String

All

ISO 8601 format

It indicates the time by which the load must be delivered to the consignee in stop's local timezone in ISO 8601 format.

CM

earliestWantTime

String

All

ISO 8601 format. If the earliestWantTime is sent, then the latestWantTime must also be sent.

It indicates the earliest time by which the load must be delivered to the consignee in the stop's local timezone in ISO 8601 format.

CM

latestWantTime

String

All

ISO 8601 format. If the latestWantTime is sent, then the earliestWantTime must also be sent.

It indicates the latest time by which the load must be delivered to the consignee in the stop's local timezone in ISO 8601 format.

CM

unloadTimeInMinutes

Integer

TL,LTL,Parcel

The value must be sent in minutes.

It indicates the dwell time to be used for the stop in ETA calculations (in minutes). When it is not provided, the company level default value will be used, if available or 90 minutes.

O

referenceNumbers

Array

All



It indicates the list of stop level reference numbers associated with the stop. These are searchable within the FourKites® platform.

CM

sequence

String

All



It indicates the stop's sequence on a load. The lower value indicates earliest scheduled stop completion. If the stop sequence is present for one stop on a load, it must be present on all stops. It is recommended to start at 1 and increment by 1 for each additional stop.

CM

customer

Object

All



It indicates the customer information for the stop.

CM

id

String

All



It is the unique identifier of the shipper's customer. The customer should have been created in FourKites® before associating it to a load's stop.

CM

name

String

All



Name of the customer to automatically pull in customer records. This field along with Id is mandatory for new customer creation.

O

poNumbers

Array

All



It indicates the list of Customer PO Numbers associated with the load's stop.

CM

pointOfContact

Array of objects

All



It indicates the point of contact (POC) information at the stop, capturing name, email, phone number, and whether they should be alerted. You can send up to 5 POCs objects per stop.

O

name

String

All



It indicates the name of the point of contact at the stop.

O

email

String

All



It indicates the email address of the point of contact at the stop.

O

phone

String

All

The ISD code followed by mobile number prepended with "+" and no special characters.

It indicates the phone number of the point of contact at the stop.

O

alert

Boolean

All

Valid values: true or false. Defaults to false.

It indicates the flag to enable or disable email notifications to the point of contact.

O

pallets

Array of objects

TL,LTL,Parcel,Rail,Ocean



It indicates the list of pallets to be delivered at the stop. Each pallet has a pallet number and list of parts.

O

number

String

TL,LTL,Parcel,Rail,Ocean



It indicates the pallet number.

O

billOfLading

String

TL,LTL,Parcel,Rail,Ocean



It indicates the bill of lading associated with the pallet record.

O

parts

Array of objects

TL,LTL,Parcel,Rail,Ocean



It indicates the list of parts in the pallet.

O

shipperPartNumber

String

TL,LTL,Parcel,Rail,Ocean



It indicates the shipper/manufacturer’s part number.

O

customerPartNumber

String

TL,LTL,Parcel,Rail,Ocean



It indicates the customer’s part number.

O

quantity

String

TL,LTL,Parcel,Rail,Ocean



It indicates the quantity of the part.

O

weight

String

TL,LTL,Parcel,Rail,Ocean



It indicates the weight of the part.

O

description

String

TL,LTL,Parcel,Rail,Ocean



It indicates the description given for the material within the pallet.

O

trackingInfo

Object

All



It indicates the information required for tracking the load.

M

truckNumber

String

TL,LTL,Parcel



It indicates the tractor or asset number dispatched by the carrier for the load.

O

trailerNumber

String

TL,LTL,Parcel



It indicates the trailer number assigned to the load.

O

driverPhone

String

TL,LTL,Parcel

The ISD code followed by mobile number prepended with "+" and no special characters. Driver Phone is required if CarrierLink mobile app for Android & iPhone is used for tracking.

It indicates a valid mobile number. Example: +13125555555

M

mawb

String

Air



The carrier’s air waybill issued to cover a consolidated shipment tendered by a forwarder or consolidator.

O

driverId

String

TL,LTL,Parcel

Driver ID is used by drivers of private fleet owners to log into CarrierLink and see the loads assigned to them. There should be an existing driver user in the platform with the same driver ID.

It indicates the driver ID used for CarrierLink access for private fleet owners.

O

deviceId

String

TL,LTL,Parcel



It indicates the ID of the GPS puck attached to the pallet or the trailer.

O

railEquipmentInitials

String

Rail

Two to Four characters

It indicates the 2 to 4 character rail equipment prefix.

O

railEquipmentNumber

String

Rail

Six characters

It indicates the load's six character rail container number.

O

wagonNumber

String

Rail



For European Rail loads, the wagonNumber field should be used instead of the railEquipmentInitials and railEquipmentNumber fields as European standards of naming/identifying rail equipments are different than other regions. If your organization intends to track rail shipments in Europe, please contact your implementation manager and request that European rail tracking be enabled along with usage of this field.

CM. This applies to Europe only. If you do not intend to track rail shipments in Europe, this field may be ignored.

vesselName

String

Ocean



It indicates the name of the vessel carrying the load.

O

imo

String

Ocean



It indicates the international maritime organization number.

O

mmsi

String

Ocean



It indicates the Maritime Mobile Service Identity (MMSI) of the vessel.

O

containerNumber

String

Ocean

ISO6346 format

It indicates the number of the container that is on the vessel. This value should be passed as load.trackingInfo.containerNumber.

M for Ocean Loads

truckRoutingParams

Object

TL,LTL,Parcel



It indicates the information required for getting truck specific routing. If provided, the routing of the truck and ETA calculations will be done based on these parameters.

O

truckType

String

TL,LTL,Parcel

Valid values: "truck" or "tractorTruck".

It specifies the vehicle type. It defaults to truck. Enum [truck , tractorTruck]

O

trailersCount

Integer

TL,LTL,Parcel

Valid values: 0, 1, 2, 3,4. Defaults to 0.

It specifies the number of trailers pulled by a vehicle.

O

shippedHazardousGoods

String

TL,LTL,Parcel

Valid values: "explosive", "gas", "flammable", "organic", "combustible", "poison", "radioActive", "corrosive", "poisonousInhalation", "harmfulToWater", "other"

It indicates the list of hazaradous materials in the vehicle. Enum [explosive , gas , flammable , organic , combustible , poison , radioActive , corrosive , poisonousInhalation , harmfulToWater , other]. The shippedHazardousGoods parameter is used in the HERE Maps API to retrieve route and distance details. This parameter is critical because certain routes prohibit the transportation of hazardous goods. By incorporating this parameter, we can ensure the selection of compliant routes, which enables accurate ETAs, precise distance calculations, and appropriate route information.

O

limitedWeight

String

TL,LTL,Parcel

Valid values: Between 0 and 1000.

It indicates the vehicle’s weight including trailers and shipped goods, in tons.

O

weightPerAxle

String

TL,LTL,Parcel

Valid values: Between 0 and 1000.

It indicates the vehicle’s weight per axle in tons.

O

height

String

TL,LTL,Parcel

Valid values: Between 0 and 50.

It indicates the vehicle’s height in meters.

O

width

String

TL,LTL,Parcel

Valid values: Between 0 and 50.

It indicates the vehicle’s width in meters.

O

length

String

TL,LTL,Parcel

Valid values: Between 0 and 300.

It indicates the vehicle’s length in meters.

O

tunnelCategory

String

TL,LTL,Parcel

Valid values: "B", "C", "D", "E"

It specifies the tunnel category to restrict certain routes. The route will pass only through tunnels of a less strict category. Enum [B , C , D , E].

O

products

Array of objects

TL,LTL



It indicates the list of temperature tracked products on a load and their temperature tracking information.

O

name

String

TL,LTL



It indicates the name of a temperature tracked product.

O

productId

String

TL,LTL

The value must already exist in FourKites®.

It indicates the FourKites®- internal unique identifier for a temperature tracked product. This is a primary key and duplicates are not allowed.

O

externalId

String

TL,LTL



It indicates the unique identifier for a product in a customer's system. This can be the same value as the productId.

O

setTemperature

String

TL,LTL



It indicates the target temperature at which the product is maintained.

O

temperatureUnit

String

TL,LTL

Valid values: "C" or "F". Defaults to "F".

It indicates the unit of the temperature in which the product is maintained. Enum ["C" , "F"]. Defaults to "F" for Fahrenheit.

O

upperTemperatureThreshold

String

TL,LTL



It indicates the upper bound (in degrees Fahrenheit) of the acceptable temperature range for a product.

O

lowerTemperatureThreshold

String

TL,LTL



It indicates the lower bound (in degrees Fahrenheit) of the acceptable temperature range for a product.

O

timeToleranceInMinutes

String

TL,LTL



It indicates the acceptable time (in minutes) for a product to maintain a temperature outside the defined temperature range. Exceeding this range for a period of time equal to or greater than this time tolerance will display a critical alert in the Temperature Tracking section of a load.

O

departingFlightNumber

String

Air



It indicates the flight number of the departing flight from the airport stop.