---
title: Request Attributes - All Load Modes
slug: fourkites-api-reference/request-attributes-all-load-modes
icon: {"faIcon":"fa-solid fa-truck"}
createdAt: 2024-01-10T12:57:59.000Z
---
:::hint{type="danger"}
### ⚠️ Important Update:
The Pallets structure is being deprecated. Please transition to for product details. [Learn more](https://docs.fourkites.com/api-reference/BXk7-create-shipment#ICU0Y)
:::
| **Object** | **Attribute** | **Format** | **Modes** | **Validation** | **Description** | **Mandatory (M)/Conditional Mandatory (CM)/Optional (O)** |
| ---------------------------------- | ------------------------------------ | --------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| additionalData | `operatingCarrierScac` | Object | All | | SCAC or code of the operating carrier if setting up managing/operating carrier | O |
| additionalData | `modeDetails` | Object | All | | It contains the mode information about the load that we create. | O |
| additionalData.modeDetails | `shipperModes` | String | All | Valid values: "TL", "LTL", "RAIL", "OCEAN", "PARCEL" | It defines the mode of the load. | O |
| additionalData.modeDetails | `carrierModes` | String | All | Valid values: "TL", "LTL", "RAIL", "OCEAN", "PARCEL" | It defines the mode of the load. | O |
| load | `load` | Object | All | | It is the parent object for the load. Place the load attributes inside this object. | M |
| load | `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 |
| load | `billOfLading` | String | TL,LTL,Parcel,Rail,Ocean | | It indicates the bill of lading associated with the Ocean load. | O |
| load | `bookingNumber` | String | Ocean | | It indicates the shipping line's booking number | O |
| load | `carrierPermalink` | String | All | | It is the unique identifier for the carrier in the FK platform. | O |
| load | `carrierName` | String | All | | It is the name of the carrier in the FK platform. | O |
| load | `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 |
| load | `shipper` | String | All | | It is the unique FourKites ID of the shipper. | M for 3 PL customers |
| load | `addressCreationSource` | String | All | | It indicates the source of address creation such as shipper, carrier, via file or via location API. | O |
| load | `transitDays` | Integer | All | | It indicates the number of days under transit for a load. | O |
| load | `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 |
| load | `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 |
| load | `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 |
| load | `proNumber` | String | All | | This is a number that is created usually after pickup or at pickup for LTL loads. | CM for LTL loads |
| load | `trackingNumber` | String | All | | It is for parcel tracking only; any tracking number provided by the carrier or other entities. | O |
| load | `seal` | String | All | | It is the seal number that identifies the seal on the load. | O |
| load | `sealStatus` | String | All | | It is the seal status that represents the status of the seal on the load. | O |
| load | `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 |
| load | `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 |
| load | `referenceNumbers` | Array | All | | It is the list of load level reference numbers associated with a load. | CM |
| load | `relayLoad` | Boolean | TL | Valid values: true or false. Defaults to false. | It indicates whether the load is relay or team load. | CM |
| load | `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 |
| load | `stops` | Array of objects | All | | It is the list of stops for the load. | M |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `name` | String | TL,LTL,Parcel,Rail | | It is the name of the stop. | M |
| load.stops | `loadingType` | String | TL,LTL,Parcel,Rail,Ocean | | Indicates whether the load or shipment is Live or Drop. Valid values : "live" or "drop" | O |
| load.stops | `addressLine1` | String | TL,LTL,Parcel,Rail | | It indicates the first line of the stop's address. | M |
| load.stops | `addressLine2` | String | TL,LTL,Parcel,Rail | | It indicates the second line of the stop's address. | O |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `postalCode` | String | TL,LTL,Parcel,Rail | | It indicates the valid postal code for the stop. | O |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `geofenceRadius` | String | TL,LTL,Parcel | | It indicates the geofence radius to be used to detect arrival and departure at this stop in meters. | O |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `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 |
| load.stops | `referenceNumbers` | Array | All | | It indicates the list of stop level reference numbers associated with the stop. These are searchable within the FourKites® platform. | CM |
| load.stops | `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 |
| load.stops | `customer` | Object | All | | It indicates the customer information for the stop. | CM |
| load.stops.customer | `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 |
| load.stops.customer | `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 |
| load.stops.customer | `poNumbers` | Array | All | | It indicates the list of Customer PO Numbers associated with the load's stop. | CM |
| load.stops.customer | `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 |
| load.stops.customer.pointOfContact | `name` | String | All | | It indicates the name of the point of contact at the stop. | O |
| load.stops.customer.pointOfContact | `email` | String | All | | It indicates the email address of the point of contact at the stop. | O |
| load.stops.customer.pointOfContact | `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 |
| load.stops.customer.pointOfContact | `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 |
| load.stops | `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 |
| load.stops.pallets | `number` | String | TL,LTL,Parcel,Rail,Ocean | | It indicates the pallet number. | O |
| load.stops.pallets | `billOfLading` | String | TL,LTL,Parcel,Rail,Ocean | | It indicates the bill of lading associated with the pallet record. | O |
| load.stops.pallets | `parts` | Array of objects | TL,LTL,Parcel,Rail,Ocean | | It indicates the list of parts in the pallet. | O |
| load.stops.pallets.parts | `shipperPartNumber` | String | TL,LTL,Parcel,Rail,Ocean | | It indicates the shipper/manufacturer’s part number. | O |
| load.stops.pallets.parts | `customerPartNumber` | String | TL,LTL,Parcel,Rail,Ocean | | It indicates the customer’s part number. | O |
| load.stops.pallets.parts | `quantity` | String | TL,LTL,Parcel,Rail,Ocean | | It indicates the quantity of the part. | O |
| load.stops.pallets.parts | `weight` | String | TL,LTL,Parcel,Rail,Ocean | | It indicates the weight of the part. | O |
| load.stops.pallets.parts | `description` | String | TL,LTL,Parcel,Rail,Ocean | | It indicates the description given for the material within the pallet. | O |
| load | `trackingInfo` | Object | All | | It indicates the information required for tracking the load. | M |
| load.trackingInfo | `truckNumber` | String | TL,LTL,Parcel | | It indicates the tractor or asset number dispatched by the carrier for the load. | O |
| load.trackingInfo | `trailerNumber` | String | TL,LTL,Parcel | | It indicates the trailer number assigned to the load. | O |
| load.trackingInfo | `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 |
| load.trackingInfo | `mawb` | String | Air | | The carrier’s air waybill issued to cover a consolidated shipment tendered by a forwarder or consolidator. | O |
| load.trackingInfo | `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 |
| load.trackingInfo | `deviceId` | String | TL,LTL,Parcel | | It indicates the ID of the GPS puck attached to the pallet or the trailer. | O |
| load.trackingInfo | `railEquipmentInitials` | String | Rail | Two to Four characters | It indicates the 2 to 4 character rail equipment prefix. | O |
| load.trackingInfo | `railEquipmentNumber` | String | Rail | Six characters | It indicates the load's six character rail container number. | O |
| load.trackingInfo | `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. |
| load.trackingInfo | `vesselName` | String | Ocean | | It indicates the name of the vessel carrying the load. | O |
| load.trackingInfo | `imo` | String | Ocean | | It indicates the international maritime organization number. | O |
| load.trackingInfo | `mmsi` | String | Ocean | | It indicates the Maritime Mobile Service Identity (MMSI) of the vessel. | O |
| load.trackingInfo | `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 |
| load | `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 |
| load.truckRoutingParams | `truckType` | String | TL,LTL,Parcel | Valid values: "truck" or "tractorTruck". | It specifies the vehicle type. It defaults to truck. Enum \[truck , tractorTruck] | O |
| load.truckRoutingParams | `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 |
| load.truckRoutingParams | `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 |
| load.truckRoutingParams | `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 |
| load.truckRoutingParams | `weightPerAxle` | String | TL,LTL,Parcel | Valid values: Between 0 and 1000. | It indicates the vehicle’s weight per axle in tons. | O |
| load.truckRoutingParams | `height` | String | TL,LTL,Parcel | Valid values: Between 0 and 50. | It indicates the vehicle’s height in meters. | O |
| load.truckRoutingParams | `width` | String | TL,LTL,Parcel | Valid values: Between 0 and 50. | It indicates the vehicle’s width in meters. | O |
| load.truckRoutingParams | `length` | String | TL,LTL,Parcel | Valid values: Between 0 and 300. | It indicates the vehicle’s length in meters. | O |
| load.truckRoutingParams | `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 |
| load | `products` | Array of objects | TL,LTL | | It indicates the list of temperature tracked products on a load and their temperature tracking information. | O |
| load.products | `name` | String | TL,LTL | | It indicates the name of a temperature tracked product. | O |
| load.products | `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 |
| load.products | `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 |
| load.products | `setTemperature` | String | TL,LTL | | It indicates the target temperature at which the product is maintained. | O |
| load.products | `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 |
| load.products | `upperTemperatureThreshold` | String | TL,LTL | | It indicates the upper bound (in degrees Fahrenheit) of the acceptable temperature range for a product. | O |
| load.products | `lowerTemperatureThreshold` | String | TL,LTL | | It indicates the lower bound (in degrees Fahrenheit) of the acceptable temperature range for a product. | O |
| load.products | `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 |
| load.stops | `departingFlightNumber` | String | Air | | It indicates the flight number of the departing flight from the airport stop. | O |