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/Shipper + one Delivery/Receiver) 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.

Request Body

Required Fields

external_reference_idstringrequired

Your unique identifier for this load

statusstringrequired

Load status. Valid values: `ACTIVE`, `TENDERED`, `TENDER_ACCEPTED`, `COVERED`, `DISPATCHED`, `AT_SHIPPER`, `EN_ROUTE`, `AT_RECEIVER`, `DELIVERED`, `COMPLETED`, `CANCELLED`

equipment_typestringrequired

Equipment type. Valid values: `DRY_VAN`, `REEFER`, `FLATBED`, `STEPDECK`, `TANKER`, etc.

transport_modestringrequired

Shipping method: `FTL`, `PTL`, or `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

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`

Request Example

curl -X POST "https://api.mentium.io/v2/tms-api/loads" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference_id": "LOAD-001",
    "status": "ACTIVE",
    "equipment_type": "DRY_VAN",
    "transport_mode": "FTL",
    "customer_external_reference_id": "CUST-ACME-001",
    "description": "Electronics shipment",
    "total_distance": 285,
    "max_buy_rate": 2200,
    "stops": [
      {
        "stop_number": 1,
        "stop_type": "Pickup",
        "location_external_reference_id": "LOC-CHICAGO-001",
        "early_arrival": "2026-02-01T08:00:00Z",
        "late_arrival": "2026-02-01T16:00:00Z"
      },
      {
        "stop_number": 2,
        "stop_type": "Delivery",
        "location_external_reference_id": "LOC-DETROIT-001",
        "early_arrival": "2026-02-02T08:00:00Z",
        "late_arrival": "2026-02-02T16:00:00Z"
      }
    ],
    "financial_rates": [
      {"rate_entity": "CUSTOMER", "amount": 3500}
    ]
  }'

Response

201 Created

{
  "id": "load_abc123def456",
  "external_reference_id": "LOAD-001",
  "status": "ACTIVE",
  "equipment_type": "DRY_VAN",
  "description": "Electronics shipment",
  "customer_id": "cust_xyz789",
  "customer_name": "Acme Corporation",
  "stops": [...],
  "created_at": "2026-01-29T10:30:00Z",
  "updated_at": "2026-01-29T10:30:00Z"
}

422 Validation Error

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "stops"],
      "msg": "Load must have at least one Pickup/Shipper stop"
    }
  ]
}