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`).

sales_repobject

Sales rep assigned to the load. See [Team member object](#team-member-object) — must include at least one of `name`, `email`, or `external_reference_id`.

dispatcher_repobject

Dispatcher rep assigned to the load. See [Team member object](#team-member-object) — must include at least one of `name`, `email`, or `external_reference_id`.

assigned_dispatcherstring

Free-text name or email for the assigned dispatcher.

actual_dispatcherstring

Free-text name or email for the actual dispatcher.

operation_userstring

Free-text name or email for the operations user.

account_managerstring

Free-text name or email for the account manager.

Team member object

sales_rep and dispatcher_rep are structured objects. All fields are optional, but at least one must be provided so Mentium can identify the member and (when possible) map them to a workspace user.

namestring

Display name (e.g. `"Jane Sales"`).

emailstring

Email address. Validated as RFC-5322 and lowercased on the way in. When an email matches a Mentium workspace user, the response includes their `mentium_user_id`.

external_reference_idstring

External reference ID for this team member from your system.

Example:

{
  "sales_rep": {
    "name": "Jane Sales",
    "email": "jane.sales@example.com",
    "external_reference_id": "USER-42"
  },
  "dispatcher_rep": {
    "email": "cara.dispatcher@example.com"
  }
}

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