Update a load
Partial update of a load: send only the fields that change; fields you omit keep their stored value. The change is applied exactly like a POST /v1/loads update of the whole load (status mapping, TMS ownership), and stops, when sent, replaces every stop. null is refused: omit a field to leave it unchanged, or send [] / "" to clear special_instructions or notes. is_posted sets Envoy’s own posted flag. carrier_rep_user_id is rejected with 422 (the rep is owned by your TMS; use POST /loads/assign-ai-agent for the AI agent). An update refused because the load belongs to the organization’s TMS returns 409 update_not_applied.
Authentication: Supports API key and bearer token authentication.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Headers
A unique key (up to 255 printable ASCII characters, e.g. a UUID) that makes a retry of this request safe. Envoy stores the response for 24 hours; a retry with the same key and the same request returns it again with Idempotent-Replayed: true instead of running twice. The same key with a different request returns 422 idempotency_key_reused; while the first request is still running, 409 idempotency_key_in_progress. 5xx and 429 responses are not stored.
Request
Envoy’s own posted flag for the load (not a TMS field).
Status supplied by the source TMS; no status is inferred when omitted
Original equipment-type string from the source TMS (e.g. ‘Van/Reefer 53”, ‘Dry Van 53FT’). Stored verbatim for audit; not used for matching.
Weight of the load (must be non-negative)
Number of miles to drive (must be non-negative)
Length in feet (must be non-negative)
Typed reference numbers for the load, as sent by the source TMS. po_numbers remains the PO-only projection used by matching/search.
Whether the source TMS has this load on hold; held loads are hidden from web/extension
Temperature run type (e.g., continuous, cycle)
Last reported longitude (-180 to 180, nullable when not moving)
Last reported latitude (-90 to 90, nullable when not moving)
Name of the customer (shipper)
Customer/shipper entity identifier from the TMS (the scheduling feed’s customer_tms_id) — not a per-shipment reference number
Sales representative name(s) reported by the source TMS; not an Envoy user assignment
Special handling instructions provided by the shipper/broker; verbalized to carriers during voice calls
Internal notes for the load. Shown in Envoy; the AI agent reads them only if your organization turns that on (carrier-facing text belongs in special_instructions).
Ordered list of stops (pickup and dropoff) - minimum 2 required
Response
Canonical equipment types used across loads, carriers, and lane preferences.
Uses StrEnum (not the class X(str, Enum) pattern) so that
str(EquipmentType.VAN) and f"{EquipmentType.VAN}" return "VAN"
instead of the default Enum.__str__ of "EquipmentType.VAN". Python
3.12 does not collapse __str__/__format__ for (str, Enum)
subclasses, which would silently corrupt every f-string and Jinja template
that interpolates an equipment type without .value.
Envoy’s own status for the load, mapped from tms_status: one of Created, Unassigned, Quotes Received, Dispatched, En Route, Delivered, Cancelled, Exception. Only Created, Unassigned and Quotes Received loads are worked by the AI agent.
When Envoy’s posted flag last turned on (UTC). Stamped by the board sync or a manual post; null if the load has not been posted since tracking began.
When Envoy’s posted flag last turned off (UTC), by a board sweep or a manual un-post; null if never un-posted.
DAT posting creation time (UTC); null when unavailable or not supplied by DAT
Sales representative name(s) reported by the source TMS; not an Envoy user assignment