---
title: "Update Load"
method: PUT
path: "/v2/tms-api/loads/{external_reference_id}"
tags: ["TMS API", "TMS API - Loads"]
---

# Update Load

`PUT /v2/tms-api/loads/{external_reference_id}`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v2/tms-api/loads/{external_reference_id}`
- Auth: none declared

Update an existing load.

## Path parameters

- `external_reference_id` string, required

## Headers

- `X-API-Key` string, nullable: API key for authentication

## Request body

- LoadUpdate: Schema for updating a load. All fields are optional.
  - `tms_status` string, nullable: Raw TMS status from your system (e.g., 'Dispatched', 'At Shipper')
  - `mentium_status` 'PLANNED' | 'ACTIVE' | 'COVERED' | 'IN_TRANSIT' | 'DELIVERED' | 'COMPLETED' | 'TERMINATED' | 'ARCHIVED' | 'TEMP' | 'MENTIUM_UNKNOWN_VALUE'
  - `equipment_type` 'DRY_VAN' | 'REEFER' | 'FLATBED' | 'FLATBED_CONESTOGA' | 'STEPDECK' | 'STEPDECK_CONESTOGA' | 'LOWBOY' | 'REMOVABLE_GOOSENECK' | 'BULK_DRY_HOPPER' | 'BULK_DRY_PNEUMATIC' | 'BULK_DRY_DUMP' | 'TANKER' | 'INTERMODAL' | 'STRAIGHT' | 'SPRINTER' | 'HOTSHOT' | 'POWER_ONLY' | 'MENTIUM_UNKNOWN_VALUE'
  - `description` string, nullable: Load description
  - `mode_type` string, nullable: Business mode (e.g., Brokerage, Asset)
  - `transport_mode` 'FTL' | 'PTL' | 'LTL' | 'MENTIUM_UNKNOWN_VALUE'
  - `service_type` string, nullable: Service type
  - `weight` number, nullable: Total weight
  - `weight_uom` 'lbs' | 'kg': Valid weight units of measure for the public TMS API.
  - `pieces` integer, nullable: Number of pieces
  - `pallet_count` integer, nullable: Number of pallets
  - `length` number, nullable: Length
  - `width` number, nullable: Width
  - `height` number, nullable: Height
  - `pickup_datetime` string, date-time, nullable: [Deprecated] Pickup date/time. Use stops[].target_arrival_earliest_at on the PICKUP stop.
  - `delivery_datetime` string, date-time, nullable: [Deprecated] Delivery date/time. Use stops[].target_arrival_earliest_at on the DELIVERY stop.
  - `earliest_pickup` string, date-time, nullable: [Deprecated] Earliest pickup. Use stops[].target_arrival_earliest_at on the PICKUP stop.
  - `latest_pickup` string, date-time, nullable: Exclusive upper bound (half-open). Emitted verbatim from the canonical `*_latest_at` column; integrators that previously interpreted this as inclusive must adjust. Deprecated — see Sunset header.
  - `earliest_delivery` string, date-time, nullable: [Deprecated] Earliest delivery. Use stops[].target_arrival_earliest_at on the DELIVERY stop.
  - `latest_delivery` string, date-time, nullable: Exclusive upper bound (half-open). Emitted verbatim from the canonical `*_latest_at` column; integrators that previously interpreted this as inclusive must adjust. Deprecated — see Sunset header.
  - `customer_external_reference_id` string, nullable: Customer external reference ID
  - `carrier_external_reference_id` string, nullable: Carrier external reference ID
  - `total_distance` number, nullable: Total distance
  - `carrier_miles` number, nullable: Carrier miles
  - `customer_miles` number, nullable: Customer miles
  - `beginning_buy_rate` number, nullable: Beginning buy rate
  - `max_buy_rate` number, nullable: Maximum buy rate
  - `mentium_booked_at` string, date-time, nullable: When the load was booked (carrier secured). Timezone-aware. Explicit value wins; if omitted and mentium_status is provided, recomputed from the status (transition into COVERED -> now, already-COVERED loads keep their value; IN_TRANSIT/DELIVERED/COMPLETED -> preserved; PLANNED/ACTIVE -> cleared).
  - `mentium_assigned_at` string, date-time, nullable: When a dispatcher was assigned. Timezone-aware. Explicit value wins; if omitted, stamped when dispatcher_rep is provided and the load is not yet assigned.
  - `stops` StopCreate[], nullable: Updated stops
    - `stop_number` integer, required: Stop sequence number
    - `stop_type` 'PICKUP' | 'DELIVERY' | 'BOTH' | 'MENTIUM_UNKNOWN_VALUE', required
    - `location_id` string, nullable: Mentium internal location ID
    - `location_external_reference_id` string, nullable: Location external reference ID from your system
    - `early_arrival` string, date-time, nullable: [Deprecated] Earliest arrival (inclusive). Use target_arrival_earliest_at.
    - `late_arrival` string, date-time, nullable: [Deprecated] Inclusive latest arrival. The canonical replacement is `target_arrival_latest_at`, which is the EXCLUSIVE upper bound of the half-open window. `late_arrival` is preserved on emission as `target_arrival_latest_at - 1 minute` so pre-PR semantics hold until the 2027-05-15 sunset. Integrators migrating to the canonical field should expect a value one minute later than `late_arrival`.
    - `target_arrival_earliest_at` string, date-time, nullable: Canonical earliest target arrival (inclusive lower bound, half-open)
    - `target_arrival_latest_at` string, date-time, nullable: Exclusive upper bound (half-open).
    - `planned_leg_start_at` string, date-time, nullable: Canonical planned-leg window start (inclusive): when the truck is planned to start the trip to this stop
    - `planned_leg_end_at` string, date-time, nullable: Canonical planned-leg window end (exclusive): when the truck is planned to end the trip at/after this stop
    - `planned_arrival_at` string, date-time, nullable: Planned arrival snapshot
    - `planned_departure_at` string, date-time, nullable: Planned departure snapshot
    - `expected_arrival_at` string, date-time, nullable: Forecast arrival
    - `expected_departure_at` string, date-time, nullable: Forecast departure
    - `actual_arrival_at` string, date-time, nullable: Recorded actual arrival
    - `actual_departure_at` string, date-time, nullable: Recorded actual departure
    - `appointment_datetime` string, date-time, nullable: [Deprecated] Scheduled appointment time. Use appointment_start_at.
    - `appointment_start_at` string, date-time, nullable: Canonical appointment window start
    - `appointment_end_at` string, date-time, nullable: Canonical appointment window end
    - `appointment_number` string, nullable: Appointment confirmation number
    - `appointment_notes` string, nullable: Appointment notes
    - `scheduling_type` 'APPOINTMENT' | 'CALL_AHEAD' | 'ETA_REQUIRED' | 'FCFS' | 'MENTIUM_UNKNOWN_VALUE', nullable: Canonical stop scheduling requirement
    - `is_appointment_required` boolean, nullable: Whether an appointment is required at this stop
    - `is_appointment_requested` boolean, nullable: Whether an appointment has been requested
    - `is_appointment_confirmed` boolean, nullable: Whether the dock appointment has been confirmed by the facility
    - `special_instruction` string, nullable: Special handling instructions
  - `requirements` ShipmentRequirementsCreate: Schema for shipment requirements. Safety Validation: - If hazmat_required=true: hazmat_class, hazmat_un_na_number, hazmat_product, hazmat_contact_number are ALL required - If temperature_controlled=true: minimum_temperature and maximum_temperature are required
    - `liftgate_required` boolean, nullable: Liftgate required
    - `pallet_jack_required` boolean, nullable: Pallet jack required
    - `blanket_wrap_required` boolean, nullable: Blanket wrap required
    - `team_service_required` boolean, nullable: Team service required
    - `driver_assist_required` boolean, nullable: Driver assist required
    - `blind_shipment` boolean, nullable: Blind shipment
    - `chains_required` boolean, nullable: Chains required
    - `chains_notes` string, nullable: Chains notes
    - `straps_required` boolean, nullable: Straps required
    - `straps_notes` string, nullable: Straps notes
    - `tarps_required` boolean, nullable: Tarps required
    - `tarp_size` string, nullable: Tarp size
    - `escorts_required` boolean, nullable: Escorts required
    - `permits_required` boolean, nullable: Permits required
    - `overdimensional` boolean, nullable: Overdimensional load
    - `twic_card_required` boolean, nullable: TWIC card required
    - `tanker_endorsement_required` boolean, nullable: Tanker endorsement required
    - `hazmat_required` boolean, nullable: Hazmat shipment
    - `hazmat_class` string, nullable: Hazmat class (REQUIRED if hazmat)
    - `hazmat_un_na_number` string, nullable: Hazmat UN/NA number (REQUIRED if hazmat)
    - `hazmat_product` string, nullable: Hazmat product name (REQUIRED if hazmat)
    - `hazmat_contact_number` string, nullable: Hazmat emergency contact (REQUIRED if hazmat)
    - `temperature_controlled` boolean, nullable: Temperature controlled
    - `minimum_temperature` integer, nullable: Minimum temperature (F) - REQUIRED if temperature_controlled
    - `maximum_temperature` integer, nullable: Maximum temperature (F) - REQUIRED if temperature_controlled
    - `precool_temperature` integer, nullable: Precool temperature (F)
  - `financial_rates` FinancialRateCreate[], nullable: Updated financial rates
    - `rate_entity` 'CARRIER' | 'CUSTOMER' | 'MENTIUM_UNKNOWN_VALUE', required
    - `charge_code` string, nullable: Charge code
    - `charge_description` string, nullable: Charge description
    - `amount` number, required: Rate amount
    - `quantity` integer, nullable: Quantity
    - `rate` number, nullable: Rate per unit
  - `is_hot` boolean, nullable: Hot/priority load
  - `is_tracking` boolean, nullable: Tracking enabled
  - `sales_rep` TeamMemberCreate: Schema for a team member assigned to a load (e.g. sales rep, capacity rep). All three fields are optional, but at least one must be provided so the member can be identified. Email is validated.
    - `name` string, nullable: Display name (e.g. 'Jane Sales')
    - `email` string, email, nullable: Email address (validated, lowercased)
    - `external_reference_id` string, nullable: External reference ID for this team member from your system
  - `dispatcher_rep` TeamMemberCreate: Schema for a team member assigned to a load (e.g. sales rep, capacity rep). All three fields are optional, but at least one must be provided so the member can be identified. Email is validated.
    - `name` string, nullable: Display name (e.g. 'Jane Sales')
    - `email` string, email, nullable: Email address (validated, lowercased)
    - `external_reference_id` string, nullable: External reference ID for this team member from your system
  - `actual_dispatcher` string, nullable: Actual dispatcher name or email
  - `operation_user` string, nullable: Operations user name or email
  - `account_manager` string, nullable: Account manager name or email

## Response `200`

Successful Response

- LoadResponse: Response schema for a load.
  - `id` string, required: Internal Mentium ID
  - `external_reference_id` string, required: External reference ID from your system
  - `tms_status` string, nullable: Raw TMS status from your system (e.g., 'Dispatched', 'At Shipper')
  - `mentium_status` string, required: Mentium normalized load status (PLANNED, ACTIVE, COVERED, IN_TRANSIT, DELIVERED, COMPLETED, TERMINATED, or the read-only ARCHIVED set by Mentium's Load auto clean, or the read-only TEMP for a load Mentium created for quoting before it exists in the TMS) - Always present
  - `equipment_type` string, nullable: Equipment type (DRY_VAN, REEFER, etc.)
  - `description` string, nullable: Load description
  - `mode_type` string, nullable: Mode type
  - `transport_mode` string, nullable: Transport mode
  - `service_type` string, nullable: Service type
  - `weight` number, nullable: Total weight
  - `weight_uom` string, nullable: Weight unit
  - `pieces` integer, nullable: Number of pieces
  - `pallet_count` integer, nullable: Number of pallets
  - `length` number, nullable: Length
  - `width` number, nullable: Width
  - `height` number, nullable: Height
  - `pickup_datetime` string, date-time, nullable: [Deprecated] Pickup arrival time. Use first PICKUP stop.actual_arrival_at / expected_arrival_at.
  - `delivery_datetime` string, date-time, nullable: [Deprecated] Delivery arrival time. Use last DELIVERY stop.actual_arrival_at / expected_arrival_at.
  - `earliest_pickup` string, date-time, nullable: [Deprecated] Earliest pickup (inclusive). Use first_pickup_stop_target_arrival_earliest_at.
  - `latest_pickup` string, date-time, nullable: Exclusive upper bound (half-open). Emitted verbatim from the canonical `*_latest_at` column; integrators that previously interpreted this as inclusive must adjust. Deprecated — see Sunset header.
  - `earliest_delivery` string, date-time, nullable: [Deprecated] Earliest delivery (inclusive). Use last_delivery_stop_target_arrival_earliest_at.
  - `latest_delivery` string, date-time, nullable: Exclusive upper bound (half-open). Emitted verbatim from the canonical `*_latest_at` column; integrators that previously interpreted this as inclusive must adjust. Deprecated — see Sunset header.
  - `first_pickup_stop_target_arrival_earliest_at` string, date-time, nullable: First-pickup stop target window start (inclusive)
  - `first_pickup_stop_target_arrival_latest_at` string, date-time, nullable: First-pickup stop target window end (exclusive)
  - `last_delivery_stop_target_arrival_earliest_at` string, date-time, nullable: Last-delivery stop target window start (inclusive)
  - `last_delivery_stop_target_arrival_latest_at` string, date-time, nullable: Last-delivery stop target window end (exclusive)
  - `customer_id` string, nullable: Customer ID
  - `customer_external_reference_id` string, nullable: Customer external reference ID
  - `customer_name` string, nullable: Customer name
  - `carrier_id` string, nullable: Carrier ID
  - `carrier_external_reference_id` string, nullable: Carrier external reference ID
  - `carrier_name` string, nullable: Carrier name
  - `total_distance` number, nullable: Total distance
  - `carrier_miles` number, nullable: Carrier miles
  - `customer_miles` number, nullable: Customer miles
  - `beginning_buy_rate` number, nullable: Beginning buy rate
  - `max_buy_rate` number, nullable: Maximum buy rate
  - `stops` StopResponse[]: Load stops
    - `id` string, required: Stop ID
    - `stop_number` integer: Stop sequence number
    - `stop_type` string, required: Type of stop
    - `location_id` string, nullable: Location ID
    - `location_external_reference_id` string, nullable: Location external reference ID
    - `location_name` string, nullable: Location name
    - `location_city` string, nullable: Location city
    - `location_state` string, nullable: Location state
    - `early_arrival` string, date-time, nullable: [Deprecated] Earliest arrival (inclusive). Use target_arrival_earliest_at.
    - `late_arrival` string, date-time, nullable: Exclusive upper bound (half-open). Emitted verbatim from the canonical `*_latest_at` column; integrators that previously interpreted this as inclusive must adjust. Deprecated — see Sunset header.
    - `actual_arrival` string, date-time, nullable: [Deprecated] Use actual_arrival_at.
    - `actual_departure` string, date-time, nullable: [Deprecated] Use actual_departure_at.
    - `appointment_datetime` string, date-time, nullable: [Deprecated] Appointment time. Use appointment_start_at.
    - `appointment_start_time` string, nullable: [Deprecated] Appointment start (HH:MM). Use appointment_start_at.
    - `appointment_end_time` string, nullable: [Deprecated] Appointment end (HH:MM). Use appointment_end_at.
    - `appointment_number` string, nullable: Appointment number
    - `appointment_notes` string, nullable: Appointment notes
    - `scheduling_type` string, nullable: Canonical stop scheduling requirement
    - `is_appointment_required` boolean, nullable: Appointment required
    - `is_appointment_requested` boolean, nullable: Appointment requested
    - `is_appointment_confirmed` boolean, nullable: Dock appointment confirmed by the facility
    - `is_appointment_made` boolean, nullable: [Deprecated] Derived: True when appointment_start_at is set.
    - `has_appointment_window` boolean, nullable: [Deprecated] Derived: True when both appointment_start_at and appointment_end_at are set.
    - `special_instruction` string, nullable: Special instructions
    - `target_arrival_earliest_at` string, date-time, nullable: Canonical earliest target arrival
    - `target_arrival_latest_at` string, date-time, nullable: Exclusive upper bound (half-open).
    - `appointment_start_at` string, date-time, nullable: Canonical appointment window start
    - `appointment_end_at` string, date-time, nullable: Canonical appointment window end
    - `planned_leg_start_at` string, date-time, nullable: Canonical planned-leg window start (inclusive)
    - `planned_leg_end_at` string, date-time, nullable: Canonical planned-leg window end (exclusive)
    - `planned_arrival_at` string, date-time, nullable: Planned arrival
    - `planned_departure_at` string, date-time, nullable: Planned departure
    - `expected_arrival_at` string, date-time, nullable: Forecast arrival
    - `expected_departure_at` string, date-time, nullable: Forecast departure
    - `actual_arrival_at` string, date-time, nullable: Actual arrival
    - `actual_departure_at` string, date-time, nullable: Actual departure
    - `created_at` string, date-time, nullable: Created timestamp
    - `updated_at` string, date-time, nullable: Updated timestamp
  - `requirements` NexusAppSchemasTmsApiLoadsShipmentRequirementsResponse: Response schema for shipment requirements.
    - `liftgate_required` boolean, nullable: Liftgate required
    - `pallet_jack_required` boolean, nullable: Pallet jack required
    - `blanket_wrap_required` boolean, nullable: Blanket wrap required
    - `team_service_required` boolean, nullable: Team service required
    - `driver_assist_required` boolean, nullable: Driver assist required
    - `blind_shipment` boolean, nullable: Blind shipment
    - `chains_required` boolean, nullable: Chains required
    - `chains_notes` string, nullable: Chains notes
    - `straps_required` boolean, nullable: Straps required
    - `straps_notes` string, nullable: Straps notes
    - `tarps_required` boolean, nullable: Tarps required
    - `tarp_size` string, nullable: Tarp size
    - `escorts_required` boolean, nullable: Escorts required
    - `permits_required` boolean, nullable: Permits required
    - `overdimensional` boolean, nullable: Overdimensional load
    - `twic_card_required` boolean, nullable: TWIC card required
    - `tanker_endorsement_required` boolean, nullable: Tanker endorsement required
    - `hazmat_required` boolean, nullable: Hazmat shipment
    - `hazmat_class` string, nullable: Hazmat class (REQUIRED if hazmat)
    - `hazmat_un_na_number` string, nullable: Hazmat UN/NA number (REQUIRED if hazmat)
    - `hazmat_product` string, nullable: Hazmat product name (REQUIRED if hazmat)
    - `hazmat_contact_number` string, nullable: Hazmat emergency contact (REQUIRED if hazmat)
    - `temperature_controlled` boolean, nullable: Temperature controlled
    - `minimum_temperature` integer, nullable: Minimum temperature (F) - REQUIRED if temperature_controlled
    - `maximum_temperature` integer, nullable: Maximum temperature (F) - REQUIRED if temperature_controlled
    - `precool_temperature` integer, nullable: Precool temperature (F)
  - `financial_rates` FinancialRateResponse[]: Financial rates
    - `id` string, required: Rate ID
    - `rate_entity` string, required: Rate entity
    - `charge_code` string, nullable: Charge code
    - `charge_description` string, nullable: Description
    - `amount` number, required: Amount
    - `quantity` integer, nullable: Quantity
    - `rate` number, nullable: Rate per unit
  - `accessorials` LoadAccessorialResponse[]: Named accessorial services selected for this load
    - `code` string, nullable
    - `name` string, required
    - `scope` string: PICKUP, DELIVERY, SHIPMENT, or UNSPECIFIED
    - `source_name` string, required: Exact spelling supplied by the source
    - `position` integer, required
  - `is_hot` boolean, nullable: Hot/priority load
  - `is_tracking` boolean, nullable: Tracking enabled
  - `sales_rep` TeamMemberResponse: Response schema for a team member assigned to a load.
    - `name` string, nullable: Display name
    - `email` string, nullable: Email address
    - `external_reference_id` string, nullable: External reference ID from your system
    - `mentium_user_id` string, nullable: Mentium user ID when this team member is mapped to a workspace user
  - `dispatcher_rep` TeamMemberResponse: Response schema for a team member assigned to a load.
    - `name` string, nullable: Display name
    - `email` string, nullable: Email address
    - `external_reference_id` string, nullable: External reference ID from your system
    - `mentium_user_id` string, nullable: Mentium user ID when this team member is mapped to a workspace user
  - `actual_dispatcher` string, nullable: Actual dispatcher name or email
  - `operation_user` string, nullable: Operations user name or email
  - `account_manager` string, nullable: Account manager name or email
  - `mentium_booked_at` string, date-time, nullable: When the load was booked (carrier secured)
  - `mentium_assigned_at` string, date-time, nullable: When a dispatcher was assigned
  - `created_at` string, date-time, required: Creation timestamp
  - `updated_at` string, date-time, required: Last update timestamp

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mentium/apis/mentium-api.md) - [All operations](https://skmtc.dev/mentium/apis/mentium-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mentium/apis/mentium-api/revisions/b4ed8e59432e?raw)