---
title: "Batch Loads"
method: POST
path: "/v2/tms-api/batch/loads"
tags: ["TMS API", "TMS API - Batch Operations"]
---

# Batch Loads

`POST /v2/tms-api/batch/loads`

## 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/batch/loads`
- Auth: none declared

Process batch load operations (create, update, upsert, delete).

- For 'create' or 'upsert': all required fields must be provided
- For 'update': only fields to update need to be provided
- For 'delete': no data needed

## Headers

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

## Request body

- BatchLoadRequest: Request schema for batch load operations.
  - `items` BatchLoadItem[], required: Batch items (max 100)
    - `operation` 'create' | 'update' | 'upsert' | 'delete', required: Batch operation types.
    - `external_reference_id` string, required: External reference ID of the load
    - `load` union: Load data (LoadCreate for create/upsert, LoadUpdate for update)
      - LoadCreate: Schema for creating a load. Required fields for analytics and carrier recommendations: - external_reference_id: Your unique load ID - tms_status: Raw TMS status from your system (optional) - mentium_status: Mentium normalized load status (PLANNED, ACTIVE, COVERED, IN_TRANSIT, DELIVERED, COMPLETED, TERMINATED) - equipment_type: Equipment type for carrier matching (DRY_VAN, REEFER, FLATBED, etc.) - transport_mode: Shipping method (FTL, PTL, LTL) - customer_external_reference_id: Link to customer - stops: At least 2 stops (Pickup + Delivery) with arrival times Note: Loads with mentium_status=TERMINATED are accepted but excluded from analytics processing. ARCHIVED is internal-only (set by Mentium's Load auto clean) and rejected on input.
        - `external_reference_id` string, required: Unique identifier from your system
        - `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', required
        - `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', required
        - `transport_mode` 'FTL' | 'PTL' | 'LTL' | 'MENTIUM_UNKNOWN_VALUE', required
        - `customer_external_reference_id` string, required: Customer external reference ID - REQUIRED
        - `description` string, nullable: Load description
        - `mode_type` string, nullable: Business mode (e.g., Brokerage, Asset)
        - `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.
        - `carrier_external_reference_id` string, nullable: Carrier external reference ID (for historical/covered loads)
        - `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` StopCreate[], required: Load stops - MUST have at least 2 (Pickup/Shipper + Delivery/Receiver)
          - `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: 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
        - `accessorials` LoadAccessorialCreate[], nullable: Named accessorial services selected for this load
          - `code` string, nullable
          - `name` string, required
          - `scope` string: PICKUP, DELIVERY, SHIPMENT, or UNSPECIFIED
          - `source_name` string, nullable
        - `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
        - `mentium_booked_at` string, date-time, nullable: When the load was booked (carrier secured). Timezone-aware. If omitted, inferred from mentium_status: COVERED -> now; IN_TRANSIT/DELIVERED/COMPLETED -> first PICKUP stop arrival; PLANNED/ACTIVE -> null.
        - `mentium_assigned_at` string, date-time, nullable: When a dispatcher was assigned. Timezone-aware. If omitted, set to now when dispatcher_rep is provided.
      - 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

- BatchResponse: Response for batch operations.
  - `success_count` integer, required: Number of successful operations
  - `error_count` integer, required: Number of failed operations
  - `results` BatchResultItem[], required: Results for each item
    - `external_reference_id` string, required: External reference ID of the item
    - `operation` 'create' | 'update' | 'upsert' | 'delete', required: Batch operation types.
    - `success` boolean, required: Whether the operation succeeded
    - `id` string, nullable: ID of created/updated entity
    - `error` string, nullable: Error message if failed
    - `error_code` string, nullable: Error code (e.g., DUPLICATE, NOT_FOUND)

## 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)