---
title: "List Loads"
method: GET
path: "/v2/tms/loads/"
tags: ["v2", "tms", "loads"]
---

# List Loads

`GET /v2/tms/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/loads/`
- Auth: HTTP bearer

List loads with flexible dynamic filtering, pagination and sorting

Query Parameters:
    - integration_connection_id: TMS integration connection ID (required)
    - filters_json: JSON array of dynamic filters supporting ALL operators
        Example: [{"field": "mentium_status", "operator": "EQUALS", "value": "ACTIVE"}]
        Supported operators:
            - EQUALS
            - NOT_EQUALS
            - GREATER_THAN
            - LESS_THAN
            - GREATER_THAN_OR_EQUAL
            - LESS_THAN_OR_EQUAL
            - CONTAINS
            - NOT_CONTAINS
            - IN
            - NOT_IN
    - limit: Maximum results (default: 50)
    - offset: Pagination offset (default: 0)
    - sort_by: Sort field (default: "first_pickup_stop_appointment_start_at")
        Stop-bound canonical fields like "first_pickup_stop_appointment_start_at",
        "last_delivery_stop_appointment_start_at", "first_pickup_stop_target_arrival_earliest_at",
        etc. route through a stop-aware LATERAL sort in Vortex.
    - sort_order: Sort order "asc" or "desc" (default: "desc")

Returns:
    List of Load models with pagination metadata in headers

## Query parameters

- `integration_connection_id` string, required
- `filters_json` string, nullable: JSON array of dynamic filters: [{"field": "miles", "operator": "EQUALS", "value": 620}] - supports ALL operators (EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, CONTAINS, etc.)
- `limit` integer
- `offset` integer
- `sort_by` string
- `sort_order` string

## Headers

- `mentium-workspace-id` string, nullable

## Response `200`

Successful Response

- LoadSchema[]
  - `id` string, required: Load UUID
  - `organization_id` string, required: Organization UUID
  - `integration_connection_id` string, required: Integration connection UUID
  - `external_reference_id` string, required: External reference ID (e.g., L302537)
  - `tms_display_reference_id` string, nullable: Human-facing reference supplied by the TMS (e.g., Turvo customId)
  - `display_reference_id` string, nullable: Connection-preferred display identifier, falling back to external_reference_id
  - `tms_status` string, nullable: Raw status from TMS system (e.g., 'Dispatched', 'At Shipper')
  - `mentium_status` string, required: Mentium mapped status (PLANNED, ACTIVE, COVERED, IN_TRANSIT, DELIVERED, COMPLETED, TERMINATED, ARCHIVED, TEMP)
  - `equipment_type` string, nullable: Equipment type (e.g., REEFER, VAN, DRY INTERMODAL TEST)
  - `description` string, nullable: Load description
  - `mode_type` string, nullable: Mode type (e.g., Brokerage, Asset)
  - `transport_mode` string, nullable: Transport mode (TL, LTL)
  - `service_type` string, nullable: Service type
  - `route_num` string, nullable: Route number
  - `is_trunk` boolean: Is trunk load
  - `is_round_trip` boolean: Is round trip
  - `is_primary_load` boolean: Is primary load
  - `length` number, nullable: Length
  - `width` number, nullable: Width
  - `height` number, nullable: Height
  - `pieces` integer, nullable: Total pieces
  - `pallet_count` integer, nullable: Total pallet count
  - `weight` number, nullable: Total weight
  - `weight_uom` string, nullable: Weight unit of measure (lbs, kg)
  - `billable_weight` number, nullable: Billable weight
  - `billable_weight_uom` string, nullable: Billable weight unit
  - `declared_value` number, nullable: Declared value
  - `ltl_reference_number` string, nullable: LTL reference number
  - `carrier_pro_number` string, nullable: Carrier PRO number
  - `beginning_buy_rate` number, nullable: Initial target offer to carriers
  - `max_buy_rate` number, nullable: Maximum negotiation ceiling
  - `buy_rates_set_at` string, date-time, nullable: When the buy rates were last set, by either an operator or the TMS
  - `buy_rates_set_by_user_id` string, nullable: Mentium user who set the buy rates; null means the TMS set them
  - `is_hot` boolean: Is hot/priority shipment
  - `priority_level` string, nullable: Priority level
  - `over_short_or_damaged` boolean: Over/short/damaged flag
  - `carrier_miles` number, nullable: Carrier miles
  - `customer_miles` number, nullable: Customer miles
  - `total_distance` number, nullable: Total distance
  - `empty_distance` number, nullable: Empty/deadhead distance
  - `trailer_length` string, nullable: Trailer length
  - `equipment_code` string, nullable: Equipment code
  - `chassis_num` string, nullable: Chassis number
  - `tractor_num` string, nullable: Tractor number
  - `trailer_number` string, nullable: Trailer number
  - `seal_number` string, nullable: Seal number
  - `driver_name` string, nullable: Driver name
  - `driver_phone` string, nullable: Driver phone
  - `first_pickup_stop_target_arrival_earliest_at` string, date-time, nullable: Canonical pickup window start (first PICKUP stop's target_arrival_earliest_at)
  - `first_pickup_stop_target_arrival_latest_at` string, date-time, nullable: Canonical pickup window end (exclusive; first PICKUP stop's target_arrival_latest_at)
  - `last_delivery_stop_target_arrival_earliest_at` string, date-time, nullable: Canonical delivery window start (last DELIVERY stop's target_arrival_earliest_at)
  - `last_delivery_stop_target_arrival_latest_at` string, date-time, nullable: Canonical delivery window end (exclusive; last DELIVERY stop's target_arrival_latest_at)
  - `elapsed_time` integer, nullable: Elapsed time in minutes
  - `transit_time` integer, nullable: Transit time in minutes
  - `created_date` string, date-time, nullable: Created date from TMS
  - `activity_date` string, date-time, nullable: Activity date
  - `rate_source` string, nullable: Rate source (SpotQuote, Contract, Manual)
  - `load_source` string, nullable: Load source (Lmws, Manual)
  - `is_tracking` boolean: Is tracking enabled
  - `tracking_link_url` string, nullable: Tracking link URL
  - `integration_status` string, nullable: Integration status (Sent, New, Pending)
  - `customer` CustomerSchema: Customer schema for OpenAPI documentation. This is the main TMS Customer object containing all customer details.
    - `id` string, required: Customer UUID
    - `organization_id` string, nullable: Organization UUID
    - `integration_connection_id` string, nullable: Integration connection UUID
    - `external_reference_id` string, nullable: External reference ID from TMS
    - `name` string, required: Customer name
    - `domain` string, nullable: Customer domain/website
    - `phone` string, nullable: Phone number
    - `fax_number` string, nullable: Fax number
    - `reference_number` string, nullable: Reference number
    - `billing_currency` string: Billing currency (USD, CAD, MXN)
    - `is_active` boolean: Whether customer is active
    - `is_parent` boolean: Whether customer is a parent account
    - `customer_type` string, nullable: Customer type (Enterprise, Mid-Market, Small Business)
    - `customer_team` string, nullable: Customer team assignment
    - `customer_division` string, nullable: Customer division
    - `ordered_by_id` string, nullable: Ordered by user ID
    - `ordered_by_name` string, nullable: Ordered by user name
    - `billing_address` AddressSchema: Reusable address schema for OpenAPI. Used by customers, carriers, contacts, and locations.
      - `id` string, nullable: Address UUID
      - `name` string, nullable: Address name/label
      - `street` string, nullable: Street address (alias for address_line1)
      - `address_line1` string, nullable: Street address line 1
      - `address_line2` string, nullable: Street address line 2
      - `city` string, nullable: City
      - `state` string, nullable: State/province
      - `postal_code` string, nullable: Postal/ZIP code
      - `country` string, nullable: Country
      - `full_text` string, nullable: Full formatted address
    - `primary_address` AddressSchema: Reusable address schema for OpenAPI. Used by customers, carriers, contacts, and locations.
      - `id` string, nullable: Address UUID
      - `name` string, nullable: Address name/label
      - `street` string, nullable: Street address (alias for address_line1)
      - `address_line1` string, nullable: Street address line 1
      - `address_line2` string, nullable: Street address line 2
      - `city` string, nullable: City
      - `state` string, nullable: State/province
      - `postal_code` string, nullable: Postal/ZIP code
      - `country` string, nullable: Country
      - `full_text` string, nullable: Full formatted address
    - `financial_summary` CustomerFinancialSummarySchema: Financial summary for a customer - revenue and margin statistics.
      - `total_revenue` number: Total revenue from all loads
      - `total_loads` integer: Total number of loads
      - `avg_revenue_per_load` number: Average revenue per load
      - `total_carrier_cost` number: Total carrier costs
      - `total_margin` number: Total margin (revenue - cost)
      - `avg_margin_percentage` number: Average margin percentage
    - `recent_loads` CustomerLoadSchema[], nullable: Recent loads for this customer
      - `id` string, required: Load UUID
      - `external_reference_id` string, required: External reference ID from TMS
      - `tms_status` string, nullable: Raw TMS status
      - `mentium_status` string, required: Mentium mapped status
      - `origin_city` string, nullable: Origin city
      - `origin_state` string, nullable: Origin state
      - `destination_city` string, nullable: Destination city
      - `destination_state` string, nullable: Destination state
      - `equipment_type` string, nullable: Equipment type
      - `first_pickup_stop_target_arrival_earliest_at` string, date-time, nullable: First PICKUP stop's target_arrival_earliest_at
      - `last_delivery_stop_target_arrival_earliest_at` string, date-time, nullable: Last DELIVERY stop's target_arrival_earliest_at
      - `total_customer_amount` number, nullable: Customer amount/revenue
      - `total_carrier_amount` number, nullable: Carrier cost
      - `created_at` string, required: Load created timestamp
    - `contacts` CustomerContactSchema[], nullable: Customer contacts
      - `id` string, required: Contact UUID
      - `customer_id` string, required: Parent customer UUID
      - `external_reference_id` string, nullable: External reference ID from TMS
      - `full_name` string, nullable: Full name
      - `first_name` string, nullable: First name
      - `last_name` string, nullable: Last name
      - `contact_type` string, nullable: Contact type (e.g., Primary Accounting)
      - `access_level` string, nullable: Access level (e.g., Accounting, Admin)
      - `is_primary` boolean: Whether this is the primary contact
      - `email` string, nullable: Email address
      - `phone` string, nullable: Phone number
      - `address_line1` string, nullable: Address line 1
      - `address_line2` string, nullable: Address line 2
      - `city` string, nullable: City
      - `state` string, nullable: State
      - `postal_code` string, nullable: Postal code
      - `country` string, nullable: Country
      - `hide_invoice_summary` boolean: Hide invoice summary flag
      - `accounting_email_required` boolean: Accounting email required flag
      - `consolidation` boolean: Consolidation flag
      - `division` string, nullable: Division
      - `role_id` string, nullable: Role ID
      - `is_active` boolean: Whether contact is active
    - `payment_term` string, nullable: Payment terms (e.g., 'Net 30')
    - `credit_limit` number, nullable: Credit limit amount
    - `created_at` string, date-time, nullable: Customer created timestamp
    - `updated_at` string, date-time, nullable: Customer last updated timestamp
  - `carriers` NexusAppSchemasTmsLoadsCarrierSchema[]: Carriers for this load
    - `id` string, required: Carrier UUID
    - `name` string, required: Carrier name
    - `dot_number` string, nullable: DOT number
    - `phone_number` string, nullable: Phone number
    - `email` string, nullable: Primary contact email
    - `external_reference_id` string, nullable: External reference ID from TMS
    - `billing_currency` string: Billing currency (USD, CAD, MXN)
  - `stops` StopSchema[]: Stops/route for this load
    - `stop_number` integer: Stop sequence number
    - `stop_type` string, required: Stop type (Pickup, Delivery)
    - `location_name` string, nullable: Location name
    - `city` string, nullable: City
    - `state` string, nullable: State
    - `postal_code` string, nullable: Postal code
    - `target_arrival_earliest_at` string, date-time, nullable: Planned earliest arrival at the stop (inclusive lower bound)
    - `target_arrival_latest_at` string, date-time, nullable: Planned latest arrival at the stop (exclusive upper bound)
    - `appointment_start_at` string, date-time, nullable: Booked appointment start (inclusive)
    - `appointment_end_at` string, date-time, nullable: Booked appointment end (exclusive)
    - `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: Dispatch's static planned arrival (3G TMS)
    - `expected_arrival_at` string, date-time, nullable: ETA forecast for arrival
    - `expected_departure_at` string, date-time, nullable: ETA forecast for departure
    - `actual_arrival_at` string, date-time, nullable: Actual arrival time
    - `actual_departure_at` string, date-time, nullable: Actual departure time
    - `appointment_number` string, nullable: Appointment number/reference
    - `appointment_notes` string, nullable: Appointment notes
    - `scheduling_type` string, 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
    - `weekday_open_hours` string, nullable: Location weekday opening hours (e.g., '08:00')
    - `weekday_close_hours` string, nullable: Location weekday closing hours (e.g., '17:00')
    - `weekend_open_hours` string, nullable: Location weekend opening hours (e.g., '09:00')
    - `weekend_close_hours` string, nullable: Location weekend closing hours (e.g., '15:00')
    - `location_id` string, nullable: Location external reference ID
    - `iana_timezone` string, nullable: IANA timezone for the stop's facility (e.g., America/Chicago)
  - `team_assignments` TeamAssignmentsSchema: Team assignments schema for load ownership.
    - `sales_rep_user_id` string, nullable: Sales rep user ID
    - `operation_user_id` string, nullable: Operations user ID
    - `actual_dispatcher_id` string, nullable: Actual dispatcher ID
    - `assigned_dispatcher_rep_user_id` string, nullable: Assigned dispatcher rep user ID
    - `account_manager_user_id` string, nullable: Account manager user ID
    - `sales_rep_name` string, nullable: Sales rep display name (TMS-captured)
    - `operation_user_name` string, nullable: Operations user display name (TMS-captured)
    - `actual_dispatcher_name` string, nullable: Actual dispatcher display name (TMS-captured)
    - `assigned_dispatcher_rep_name` string, nullable: Assigned dispatcher rep display name (TMS-captured)
    - `account_manager_name` string, nullable: Account manager display name (TMS-captured)
    - `sales_executive_user_id` string, nullable: Sales executive user ID
    - `primary_internal_contact_id` string, nullable: Primary internal contact ID
    - `business_development_rep_user_id` string, nullable: Business development rep user ID
  - `financial_summary` FinancialSummarySchema: Financial summary schema for load profitability.
    - `total_customer_amount` number, nullable: What customer pays broker (revenue)
    - `total_carrier_amount` number, nullable: What broker pays carrier (cost)
    - `net_margin_amount` number, nullable: Profit (revenue - cost)
    - `net_margin_percentage` number, nullable: Margin percentage
  - `engagement_metrics` EngagementMetricsSchema: Carrier engagement metrics for load board.
    - `contacted_count` integer: Number of unique carriers contacted for this load
    - `responses_count` integer: Number of unique carriers who responded
  - `accessorials` LoadAccessorialSchema[]: Named services selected on this load
    - `code` string, nullable: Source accessorial code when supplied
    - `name` string, required: Normalized carrier-facing service name
    - `scope` string, required: PICKUP, DELIVERY, SHIPMENT, or UNSPECIFIED
    - `source_name` string, required: Exact source spelling retained for audit
    - `position` integer: Stable per-load source order (0-based)
  - `assigned_to` string, nullable: Assigned dispatcher name
  - `offer_statuses` CarrierOfferStatus[]: Distinct carrier offer statuses for the load
  - `late_tracking_status` string, nullable: Late-load tracking status when the load has an active late episode (LATE)
  - `analytics_error_category` string, nullable: Category of the analytics error (INTERNAL_ERROR, EXTERNAL_DATA_VALIDATION, SKIPPED)
  - `analytics_error_description` string, nullable: Description of the analytics error
  - `batch_analytics` boolean: True if analytics processing is pending
  - `lane_historical_load_count` integer, nullable: All-time analyzed load count on this load's lane. None when no analytics history exists.
  - `lane_historical_margin` number, nullable: All-time total margin (customer − carrier) on this load's lane. Drives the lane P/L tag (>0 profit, <0 loss, 0 break-even).
  - `customer_historical_load_count` integer, nullable: All-time analyzed load count for this load's customer. None when no analytics history exists.
  - `customer_historical_margin` number, nullable: All-time total margin (customer − carrier) for this load's customer. Drives the customer P/L tag (>0 profit, <0 loss, 0 break-even).
  - `archived_at` string, date-time, nullable: When the load was auto-archived
  - `archive_reason` string, nullable: Human-readable reason the load was archived
  - `external_link` string, nullable: External TMS link to view load
  - `sales_rep_display_name` string, nullable: Sales rep display name (from TMS user info or mapping)
  - `sales_rep_mentium_user_id` string, nullable: Mentium user ID when sales rep is mapped to a workspace user
  - `assigned_dispatcher_rep_display_name` string, nullable: Assigned dispatcher rep display name (from TMS user info or mapping)
  - `assigned_dispatcher_rep_mentium_user_id` string, nullable: Mentium user ID when assigned dispatcher rep is mapped to a workspace user
  - `actual_dispatcher_display_name` string, nullable: Actual dispatcher display name (from TMS user info or mapping)
  - `actual_dispatcher_mentium_user_id` string, nullable: Mentium user ID when actual dispatcher is mapped to a workspace user
  - `created_at` string, date-time, required: Record created timestamp
  - `updated_at` string, date-time, required: Record updated 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)