Skip to navigation
EndpointsLoads

Create a load

Create or update a freight load. A load with the same tms_load_id or load_number is updated: 201 when the load was created, 200 when an existing load was updated.

Authentication: API key required.

Headers

Idempotency-KeystringOptional<=255 characters

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

This endpoint expects an object.
load_numberstringRequired>=1 character
Unique load reference number
equipment_typeenumRequired
Equipment type used for transport
stopslist of objectsRequired

Ordered list of stops (pickup and dropoff) - minimum 2 required

equipment_type_rawstring or nullOptional

Original equipment-type string from the source TMS (e.g. ‘Van/Reefer 53”, ‘Dry Van 53FT’). Stored verbatim for audit; not used for matching.

modeenum or nullOptional
Transport mode, when supplied by the source
tms_load_idstring or nullOptional1-64 characters

Your TMS’s ID for the load. Envoy matches updates on it (then on load_number), so keep it stable for the life of the load.

tms_statusstring or nullOptional

Status supplied by the source TMS; no status is inferred when omitted

weightdouble or nullOptional>=0

Weight of the load (must be non-negative)

distancedouble or nullOptional>=0

Number of miles to drive (must be non-negative)

commoditystring or nullOptional
Commodity being hauled
handling_unit_countinteger or nullOptional>=0
Number of freight handling units
handling_unit_typestring or nullOptional
Type of freight handling unit, e.g. pallet or case
po_numberslist of strings or nullOptional
List of PO or pickup numbers
reference_numberslist of objects or nullOptional

Typed reference numbers for the load, as sent by the source TMS. po_numbers remains the PO-only projection used by matching/search.

posted_rateinteger or nullOptional
Posted rate in USD
max_buy_rateinteger or nullOptional
Maximum buy rate in USD
suggested_market_rateinteger or nullOptional
Suggested market rate in USD
length_feetinteger or nullOptional>=0

Length in feet (must be non-negative)

carrier_completed_ratedouble or nullOptional
Rate the carrier completed the load at, in USD
customer_ratedouble or nullOptional
Rate quoted to the customer, in USD
margindouble or nullOptional
Margin in USD as reported by the source TMS
hold_loadbooleanOptionalDefaults to false

Whether the source TMS has this load on hold; held loads are hidden from web/extension

actionenum or nullOptional

Caller intent for this row (CSV upload). NEW = create (error if it already exists); UPDATE = update (error if it does not exist); INACTIVATE = update + hold_load=true. When omitted, the row is upserted (legacy behavior).

Allowed values:
temperature_setting_minimuminteger or nullOptional
Minimum temperature setting in degrees
temperature_setting_maximuminteger or nullOptional
Maximum temperature setting in degrees
temperature_run_typestring or nullOptional

Temperature run type (e.g., continuous, cycle)

last_reported_statestring or nullOptional
Last reported state for tracking
last_reported_citystring or nullOptional
Last reported city for tracking
last_reported_longdouble or nullOptional-180-180

Last reported longitude (-180 to 180, nullable when not moving)

last_reported_latdouble or nullOptional-90-90

Last reported latitude (-90 to 90, nullable when not moving)

tms_carrier_idstring or nullOptional
Your TMS's ID for the carrier hauling the load
carrier_namestring or nullOptional
Name of the carrier
customer_namestring or nullOptional

Name of the customer (shipper)

customer_refstring or nullOptional

Customer/shipper entity identifier from the TMS (the scheduling feed’s customer_tms_id) — not a per-shipment reference number

tms_sales_rep_namesstring or nullOptional

Sales representative name(s) reported by the source TMS; not an Envoy user assignment

carrier_repobject or nullOptional
Carrier Sales Representative contact details
driverobject or nullOptional
Driver contact details
special_instructionslist of strings or nullOptional

Special handling instructions provided by the shipper/broker; verbalized to carriers during voice calls

notesstring or nullOptional

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

custom_fieldsmap from strings to any or nullOptional

Additional custom fields for source-specific data

Response

An existing load was updated
idstringformat: "^load_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
Envoy load ID
operationenum
Whether the load was created or updated
Allowed values:
messagestring
processed_atdatetime
load_idstringDeprecated

Deprecated: the same load as id, without the load_ prefix. Use id.

successbooleanOptionalDefaults to true

Errors

401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error