Step 5. Create a load.

As a freight partner, you post loads to your Smart Load Board using a POST call to the loads endpoint. The load object is one of the most significant components of the Freight Marketplace. It contains all the details for the specific shipment; many of these are objects in themselves. These include but are not limited to:

  • the shipment's origin and destination (each load must have a minimum of these two stops in its itinerary)
  • actions allowed on the shipment, such as book and/or bid
  • status for the load (expired, valid, covered, etc.); note that this parameter is the only way to "delete" a load (remove it from the Smart Load Board): by setting its value to 'STATUS_CANCELED', 'STATUS_COVERED', 'STATUS_EXPIRED', OR 'STATUS_RESERVED'.
  • specifications describing the load, such as rate and weight
  • load-specific visibility
  • load-specific override of the carrier allowlist
  • extra shipment information

The load object contains numerous arrays of objects, so in addition to top-level parameters describing the load, there are many nested objects as well. All are described in this article. Let's begin.

load: Top-Level Object

The load object is the top-level object. At this level, provide the following parameters:

  • load_reference: This required String is the load reference number from your system of record. Example: "load_reference": "abcnostrudculpa2".
  • status: This required String (example: "status": "STATUS_OPEN") is an enum with the following possible values:
    • STATUS_OPEN: This is the default value. It means that the load is available to be booked by eligible carriers. Only open loads are displayed on the Smart Load Board.
    • STATUS_COVERED: A load with this status does not display on the Smart Load Board. The load has been assigned to a carrier.
    • STATUS_CANCELED: A load with this status does not display on the Smart Load Board. The load is no longer available. Because the Freight Marketplace API does not support load deletion, use the status parameter set to this value to remove a load from the Smart Load Board.
    • STATUS_EXPIRED: A load with this status does not display on the Smart Load Board. The expired_at timestamp has now passed. By default, the expired_at timestamp is set to the pickup appointment time or to the pickup window end.
    • STATUS_RESERVED: A load with this status does not display on the Smart Load Board. The load has not yet been covered, but is being held for some reason (for example, if a carrier is actively negotiating a rate).
  • mode: This String is a required enum that describes to the trucking modes required to carry freight. It accepts the following possible values:
    • MODE_FTL: This is the default value. Full truck load (FTL) requires the entire space available in the truck to carry the freight between two shipping locations.
    • MODE_LTL: This value is not yet supported by this API. A less than truckload (LTL) typically does not fill the entire truck, which leaves space for additional shipments.
    • MODE_PARTIAL: Partial truck load is a load whose volume does not justify a full truck load. Not all carriers offer partial truck load services.
    • MODE_DRAYAGE: This value is not yet supported by this API. This mode refers to the transport of cargo over a short distance by truck, or as part of a longer distance.
    • MODE_INTERMODAL: This value is not yet supported by this API. Intermodal means that the distance is covered over some combination of sea, rail, and/or truck.
  • book_now_eligible: This boolean indicates whether the load is eligible for the Book Now option to alllowlisted carriers. Its default value is 'true'; if set to 'false', this load won't display for a carrier to "book now" even if the carrier is allowlisted. Set it to 'false' to override the carrier allowlist. If 'true', the booking rate is specified in the rate parameter below.
  • bid_eligible: This boolean indicates whether the load is eligible for the Bid option to alllowlisted carriers. Its default value is 'true'; if set to 'false', this load won't display for a carrier to "Bid" on, even if the carrier is allowlisted. Set it to 'false' to override the carrier allowlist.
  • allowlist_only: If set to 'true', this boolean indicates that the load can only be displayed to allowlisted carriers. Its default value is 'false', meaning that by default the load is displayed to all carriers.
  • trailer_types: This array of strings is required. It describes the trailer type needed for this load, such as TRAILER_TYPE_FLATBED, TRAILER_TYPE_STEPDECK, TRAILER_TYPE_CONTAINER, TRAILER_TYPE_TANKER, etc. Refer to our Freight Marketplace API reference article for creating a load for a comprehensive list of all accepted values.
  • trailer_length: This required int64 value indicates the length of the trailer needed to haul this load.
  • weight: This required float indicates the weight of the load, in pounds.
  • rate: This int64 value indicates the posted rate for booking this load. This value only applies to and is required for bookable loads: loads whose book_now_eligible value is 'true'.
  • currency_code: This String specifies the currency of the monetary fields in this object, and defaults to 'CURRENCY_CODE_USD'. USD is the only currency we support at this time.
  • shipper: An optional String identifying the shipper.
  • commodity: A required String identifying the commodity being hauled.
  • cargo_insurance: An optional int64 value specifying the minimum cargo insurance required to haul this load.
  • comments: An optional String for free-form comments about this load.
  • expired_time: The date-time at which this posting should expire. The expiration cannot be later than the pickup time (or window end). If not provided, this value defaults to the pickup time (or window end).
  • freight_partner_internal_load_id: This optional String will be used in any templatized redirect URLs that you provide. If you do not provide this field, we assume its value equals the load_reference for this load.

📘

Note

The Freight Marketplace API does not support deletion of loads. To remove a load from the Smart Load Board, update the load’s status; refer to Step 6. Update or delete a load.

load.itinerary Object

Itinerary is a required, ordered array of objects representing stops for this load. Each load must have a minimum of two stops (origin and destination). Ordered means that all itinerary times must be provided in chronological order. Only U.S. zip codes are currently supported.

  • facility_name: This String is the name of the facility (the name of the stop).
  • type: This required String is the type of the stop (reason for the stop). There is no default value. Accepted values are: TYPE_PRELOADED_TRAILER_PICKUP,TYPE_LIVE_UNLOAD,TYPE_LIVE_PICKUP, TYPE_EMPTY_TRAILER_PICKUP, TYPE_EMPTY_TRAILER_RETURN, TYPE_DROP_LOADED_TRAILER, TYPE_CHANGE_DRIVER, TYPE_CHANGE_POWER_UNIT, TYPE_CHANGE_TRAILER, TYPE_CHANGE_MULTIPLE, TYPE_BORDER_STOP.
  • instructions: This optional String can contain instructions for the carrier that are specific to this stop on the itinerary.

load.itinerary.address Object

This required object defines the location of a stop on the itinerary. It is a generic address object. street_address1 and street_address2 are optional Strings, whereas city, state, country, and zip are all required Strings.

load.itinerary.appointment Object

Appointment refers to pick-up and drop-off times. Every itinerary must have a minimum of two appointment objects: a pickup time provided with the origin, and a drop-off time provided with the destination.

  • type: This required String describing which time is being provided. Acceptable values are: 'TYPE_FIXED' for fixed-time appointments, and 'TYPE_FCFS' for first-come-first-served appointments.
  • open_time: This is a required RFC3339 date-timestamp with timezone.
  • close_time: This is an RFC3339 date-timestamp with timezone. It is required if type = 'TYPE_FCFS' but must be left null if type = 'TYPE_FIXED'.

load.itinerary.contact Object

This is an optional object containing contact information for a stop.

  • email: Optional String with the contact's email.
  • phone: Optional String with the contact's phone.
  • website: Optional String with the contact's website.

load.itinerary.lat_lng Object

This is an optional object representing a latitude/longitude pair. It is expressed as a
pair of doubles to represent degrees latitude and degrees longitude. Unless
specified otherwise, this value must conform to the WGS84 standard. Values must be within normalized ranges.

  • latitude: The latitude in degrees. It must be in the range [-90.0, +90.0].
  • longitude: The longitude in degrees. It must be in the range [-180.0, +180.0].

load.load_requirements Object

This array of key-value pairs describes additional requirements for carrying the load, such as the maximum temperature of the trailer, required tarp size, or the need for an alcohol permit. Each key-value pair consists of the name of the requirement as the key followed by the value, a String defining the specific value for a requirement.

The key String is an enum whose acceptable values include REQUIREMENT_MIN_TEMP, REQUIREMENT_STRAP_COUNT or REQUIREMENT_LIFT_GATE, etc. Refer to our Freight Marketplace API reference article for creating a load for a comprehensive list of all accepted load requirements. An example load requirement object may specify a minimum temperature of 32.

load.contact Object

This is a required object containing contact information for this load.

  • phone: A required String containing the contact phone number for the contact for this load. Format: +12345678901.
  • email: An optional String containing the email for the contact for this load.

Response: Load ID

A successful response payload consists of the load ID. You will need this ID to update or delete a load or to view a load's details.

📘

Learn more

Read our reference documentation for the Freight Marketplace API's loads endpoint.

Language
Authorization
OAuth2
Click Try It! to start a request and see the response here!