Loads

Get a load

Changed on

Retrieve a load by ID.

The response includes embedded carriers and stops.

get/loads/{id}

Request

  • Base URL: https://api.mvmnt.io/v1
  • URL: https://api.mvmnt.io/v1/loads/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

Resource ID (UUID) or client key

Query parameters

by'id' | 'key'

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Response

Load retrieved successfully

idstring uuid required
friendlyIdstring

Human-readable load ID (e.g., "LD-12345")

keystring nullable

Client-defined reference identifier for this load

shipmentIdstring uuid

Parent shipment

shipmentKeystring nullable

Parent shipment human-readable ID (friendlyId)

mode'FTL' | 'TL' | 'LTL' | 'PTL' | 'RLTL' | 'BULK' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE' | 'AUTO' | 'EXPEDITED_AIR' | 'EXPEDITED_GROUND'

Transportation mode. Optional on write — a shipment or load created without one is stored with no mode, the same as one created in the TMS.

  • FTL: Full Truckload — the value the TMS stores and always returns
  • TL: legacy spelling of FTL, still accepted on write, never returned
  • LTL: Less than Truckload
  • PTL: Partial Truckload
  • RLTL: Retail LTL
  • BULK: Bulk truckload freight
  • AUTO: Auto transport
  • EXPEDITED_AIR: Expedited air
  • EXPEDITED_GROUND: Expedited ground
  • AIR: Air freight
  • OCEAN: Ocean freight
  • RAIL: Rail freight
  • INTERMODAL: Intermodal (multiple modes)
  • DRAYAGE: Drayage/cartage
status'SOURCING' | 'SELECTED' | 'BOOKED' | 'DISPATCHED' | 'LOADING' | 'PICKED_UP' | 'IN_TRANSIT' | 'UNLOADING' | 'ARRIVED_AT_DELIVERY_TERMINAL' | 'OUT_FOR_DELIVERY' | 'RECOVERED' | 'DELIVERED_AWAITING_INVOICE' | 'DELIVERED_INVOICE_IN_REVIEW' | 'DELIVERED_APPROVED_TO_BE_PAID' | 'DELIVERED_PAID' | 'COMPLETE' | 'SERVICE_FAILURE' | 'ON_HOLD' | 'CANCELED' required

Current status of the load.

Pre-transit:

  • SOURCING: Looking for carrier
  • SELECTED: Carrier selected
  • BOOKED: Carrier booked
  • DISPATCHED: Dispatched to carrier

In-transit:

  • LOADING: Loading at pickup
  • PICKED_UP: Picked up
  • IN_TRANSIT: In transit
  • UNLOADING: Unloading at delivery
  • ARRIVED_AT_DELIVERY_TERMINAL: Arrived at delivery terminal
  • OUT_FOR_DELIVERY: Out for delivery
  • RECOVERED: Recovered after a service issue

Delivered (accounts payable lifecycle):

  • DELIVERED_AWAITING_INVOICE: Delivered, awaiting carrier invoice
  • DELIVERED_INVOICE_IN_REVIEW: Carrier invoice in review
  • DELIVERED_APPROVED_TO_BE_PAID: Approved to be paid
  • DELIVERED_PAID: Paid

Final / exceptions:

  • COMPLETE: Complete
  • SERVICE_FAILURE: Service failure
  • ON_HOLD: On hold
  • CANCELED: Canceled
totalCostnumber nullable

Total carrier costs

createdAtstring date-time required
updatedAtstring date-time nullable
pickedUpAtstring date-time nullable
deliveredAtstring date-time nullable

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "LD-12345",
  "key": "my-load-001",
  "stops": [
    {
      "address": {
        "line1": "123 Main St",
        "line2": "Suite 400",
        "city": "Chicago",
        "state": "IL",
        "zipCode": "60601",
        "country": "USA",
        "market": "CHI",
        "latitude": "41.8781",
        "longitude": "-87.6298",
        "isSmartyValidated": true,
        "obeysDst": true
      }
    }
  ],
  "carriers": [
    {
      "carrier": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "key": "ERP-CARRIER-SWIFT",
        "name": "Swift Transportation",
        "phoneNumber": "+1-555-987-6543",
        "email": "dispatch@swifttrans.com",
        "createdAt": "2025-01-15T10:00:00Z",
        "updatedAt": "2025-01-15T14:30:00Z"
      }
    }
  ]
}

Changes

  • 2cd6ecfbeb82Revision changes
    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      added the new DROP enum value to the // response property for the response status

    • warning

      added the new PICK enum value to the // response property for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      removed the DELIVERY enum value from the // response property for the response status

    • info

      removed the PICKUP enum value from the // response property for the response status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • 66fb538125abRevision changes
    • info

      added the optional property // to the response with the status