Create Load

POST /v2/tms-api/loads

Create a new load/shipment. Loads require specific fields for analytics and carrier recommendations to work properly.

Required Fields

The following fields are required for loads to work with analytics and carrier recommendations:

• status: Load status (must be a valid enum value)
• equipment_type: Equipment type (must be a valid enum value)
• transport_mode: Shipping method (FTL, PTL, or LTL)
• customer_external_reference_id: Link to an existing customer
• stops: At least 2 stops (one PICKUP + one DELIVERY) with early_arrival and late_arrival times

Prerequisites

Locations must be created before loads. Each stop references a location by location_external_reference_id, and the API will return an error if the location doesn't exist.

API Reference

Request Body

Source of truth for enums

The allowed enum values below come from the Mentium canonical enums in libs/libs/mentium_tms/enums.py (which are imported by the TMS API request schemas). FastAPI validates these fields at the API boundary.

Required Fields

external_reference_idstringrequired

Your unique identifier for this load

statusstringrequired

Load status (**LoadStatus** enum — see “Allowed enum values” below)

equipment_typestringrequired

Equipment type (**EquipmentType** enum — see “Allowed enum values” below)

transport_modestringrequired

Shipping method (**ShippingMethod** enum — `FTL`, `PTL`, `LTL`)

customer_external_reference_idstringrequired

External reference ID of an existing customer

stopsarrayrequired

Array of stops (minimum 2). Must include at least one Pickup and one Delivery stop.

Optional Fields

descriptionstring

Load description

weightnumber

Total weight

weight_uomstring

Weight unit (**WeightUOM** enum — `lbs`, `kg`)

total_distancenumber

Total distance in miles

max_buy_ratenumber

Maximum buy rate

carrier_external_reference_idstring

External reference ID of carrier (for historical loads)

financial_ratesarray

Array of financial rates with `rate_entity` and `amount`. `rate_entity` is a **RateEntity** enum (`CUSTOMER` or `CARRIER`).

Allowed enum values

LoadStatus (status)

• ACTIVE
• TENDERED
• TENDER_ACCEPTED
• SPOT
• COVERED
• DISPATCHED
• AT_SHIPPER
• EN_ROUTE
• AT_RECEIVER
• DELIVERED
• PAYMENT_PROCESSING
• ACCOUNTING_REVIEW
• COMPLETED
• CANCELLED
• TENDER_REJECTED
• INACTIVE
• ON_HOLD

EquipmentType (equipment_type)

• DRY_VAN
• REEFER
• FLATBED
• FLATBED_CONESTOGA
• STEPDECK
• STEPDECK_CONESTOGA
• LOWBOY
• REMOVABLE_GOOSENECK
• TANKER
• INTERMODAL
• STRAIGHT
• SPRINTER
• HOTSHOT
• POWER_ONLY
• BULK_DRY_HOPPER
• BULK_DRY_PNEUMATIC
• BULK_DRY_DUMP

ShippingMethod (transport_mode)

• FTL (Full Truckload)
• PTL (Partial Truckload)
• LTL (Less Than Truckload)

StopType (stops[].stop_type)

• PICKUP
• DELIVERY
• BOTH

RateEntity (financial_rates[].rate_entity)

• CUSTOMER
• CARRIER

WeightUOM (weight_uom)

• lbs
• kg