> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.tryenvoy.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tryenvoy.ai/_mcp/server. # Get a load GET https://tryenvoy.ai/api/v1/loads/{load_id} Get a single load by ID. **Authentication:** Supports API key and bearer token authentication. Reference: https://docs.tryenvoy.ai/api-reference/endpoints/loads/get ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://tryenvoy.ai/api/v1` (Production, default) - `https://staging.tryenvoy.ai/api/v1` (Staging) ## Request ### Path parameters - `load_id` (string, required) ### Headers - `X-Organization-ID` (string, optional, nullable) ## Response ### 200 Successful Response - `id` (string, required) - `load_number` (string, required) - `organization_id` (string, required) - `equipment_type` (enum, required) — 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`. - Allowed values: `VAN`, `REEFER`, `FLATBED`, `STEPDECK`, `RGN`, `CONESTOGA`, `BOX_TRUCK`, `CONTAINER`, `INTERMODAL`, `POWER_ONLY`, `TANKER`, `LOWBOY`, `HOTSHOT`, `AUTO_CARRIER`, `DRY_BULK`, `DRY_TEAM`, `REEFER_TEAM`, `LTL`, `OTHER`, `VAN/REEFER` - `created_at` (datetime, required) - `updated_at` (datetime, required) - `tms_load_id` (string, optional, nullable) - `external_id` (string, optional, nullable) - `mode` (enum, optional) - Allowed values: `FTL`, `PTL`, `LTL`, `DED`, `RAIL`, `PASS` - `load_status` (string, optional, nullable) — 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. - `tms_status` (string, optional, nullable) - `weight` (double, optional, nullable) - `distance` (double, optional, nullable) - `commodity` (string, optional, nullable) - `handling_unit_count` (integer, optional, nullable) — Number of freight handling units - `handling_unit_type` (string, optional, nullable) — Type of freight handling unit, e.g. pallet or case - `po_numbers` (list of string, optional, nullable) - `reference_numbers` (list of ReferenceNumber, optional, nullable) - `posted_rate` (integer, optional, nullable) - `max_buy_rate` (integer, optional, nullable) - `suggested_market_rate` (integer, optional, nullable) - `length_feet` (integer, optional, nullable) - `special_instructions` (list of string, optional, nullable) - `notes` (string, optional, nullable) - `is_posted` (boolean, optional, default: false) - `last_posted_at` (datetime, optional, nullable) — 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. - `last_unposted_at` (datetime, optional, nullable) — When Envoy's posted flag last turned off (UTC), by a board sweep or a manual un-post; null if never un-posted. - `externally_posted_at` (datetime, optional, nullable) — DAT posting creation time (UTC); null when unavailable or not supplied by DAT - `temperature_setting_minimum` (integer, optional, nullable) - `temperature_setting_maximum` (integer, optional, nullable) - `temperature_run_type` (string, optional, nullable) - `last_reported_state` (string, optional, nullable) - `last_reported_city` (string, optional, nullable) - `last_reported_long` (double, optional, nullable) - `last_reported_lat` (double, optional, nullable) - `tms_carrier_id` (string, optional, nullable) - `carrier_name` (string, optional, nullable) - `hauling_carrier_id` (string, optional, nullable) - `hauling_carrier_name` (string, optional, nullable) - `hauling_carrier_mc_number` (string, optional, nullable) - `hauling_carrier_dot_number` (string, optional, nullable) - `carrier_completed_rate` (double, optional, nullable) — What the carrier that moved the load is paid, in USD, as reported by the TMS - `customer_rate` (double, optional, nullable) — The customer's rate in USD, as reported by the TMS. Returned to API keys and org admins only - `margin` (double, optional, nullable) — Margin in USD, as reported by the TMS. Returned to API keys and org admins only - `customer_name` (string, optional, nullable) - `tms_sales_rep_names` (string, optional, nullable) — Sales representative name(s) reported by the source TMS; not an Envoy user assignment - `carrier_rep` (Contact, optional, nullable) — Contact information for various parties involved in the load - `driver` (Contact, optional, nullable) — Contact information for various parties involved in the load - `carrier_rep_user_id` (string, optional, nullable) - `carrier_rep_user_name` (string, optional, nullable) - `carrier_rep_user_email` (string, optional, nullable) - `assigned_to_ai_agent` (boolean, optional, default: false) - `stops` (list of StopResponse, optional) - `context` (map from string to any, optional) - `custom_fields` (map from string to any, optional) - `offer_count` (integer, optional, default: 0) — Number of unique carrier offers received - `max_offer_amount` (double, optional, nullable) — Highest offer amount received - `min_offer_amount` (double, optional, nullable) — Lowest offer amount received - `active_escalation_count` (integer, optional, default: 0) — Number of ACTIVE escalations anchored to this load ## Errors ### 401 Unauthorized Error Not authenticated - missing or invalid token/API key - `any` ### 403 Forbidden Error Insufficient permissions for this operation - `any` ### 404 Not Found Error Resource not found - `any` ### 422 Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ### 429 Too Many Requests Error Rate limit exceeded - see Retry-After header - `any` ## Types ### ReferenceNumber One typed reference number from a source TMS (stop- or load-level). ``type`` is the source's own label ("Shipper Reference Number", "PO Number", "Shipment Id", ...) kept as display text rather than an enum: every TMS names these differently and customers define their own beyond any standard table, so an enum would silently drop the custom ones. Callers that need typed routing resolve the label at the source boundary (see ``tai/reference_types.py``) and keep the raw string here. - `value` (string, required) — The reference number itself - `type` (string, optional, nullable) — Source TMS label for this reference (display text) ### Contact Contact information for various parties involved in the load - `type` (enum, optional, nullable) — Role of the contact (for TMS compatibility) - Allowed values: `CARRIER`, `DISPATCHER`, `DRIVER`, `TENDERING`, `QUOTING`, `OTHER` - `first_name` (string, optional, nullable) — First name of the contact - `last_name` (string, optional, nullable) — Last name of the contact - `phone` (string, optional, nullable) — Phone number — stored as E.164 when parseable, None otherwise - `email` (string, optional, nullable) — Email address ### StopResponse The domain Stop with its row id prefixed (stop\_\*). Tracking check-ins reference stops by this id (POST /tracking/loads/\{load\_id}/prompt). - `location` (Location, required) — Location details of the stop - `id` (string, optional, nullable) - `stop_number` (integer, optional, nullable) — Sequence number of the stop - `is_pickup` (boolean, optional, nullable) — True if this stop is a pickup - `is_dropoff` (boolean, optional, nullable) — True if this stop is a dropoff - `expected_date` (datetime, optional, nullable) — Expected date of activity at this stop - `contact` (Contact, optional, nullable) — Contact details at the stop (singular, for backward compatibility) - `type` (enum, optional, nullable) — Type of stop: exactly `Pickup` or `Dropoff` (case-sensitive; other spellings are rejected) - Allowed values: `Pickup`, `Dropoff` - `planned` (PlannedArrival, optional, nullable) — Planned arrival window - `pickup_delivery_number` (string, optional, nullable) — PO or pickup number; also the place for the source TMS's own stop identifier - `contacts` (list of Contact, optional, nullable) — List of contacts at this stop - `actual_stop_times` (ActualStopTimes, optional, nullable) — Actual arrival and departure times - `carrier_eta` (datetime, optional, nullable) — Carrier's estimated time of arrival - `reference_numbers` (list of ReferenceNumber, optional, nullable) — Typed reference numbers for this stop, as sent by the source TMS - `notes` (string, optional, nullable) — Stop notes from the source TMS. DISPLAY ONLY — kept out of the voice/email agent context; carrier-facing text belongs in special_instructions. - `special_instructions` (list of string, optional, nullable) — Stop-level handling instructions (titled sections), verbalized to carriers ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (ValidationErrorCtx, optional) ### Location Location information for stops - `city` (string, required) — City of the location - `state` (string, required) — State or province code - `street` (string, optional, nullable) — Street address of the location - `postal_code` (string, optional, nullable) — Postal or ZIP code - `country` (string, optional, nullable, default: US) — Country code (ISO-3166-1 alpha-2), defaults to US - `company_name` (string, optional, nullable) — Company name at this location - `county` (string, optional, nullable) — County name - `latitude` (double, optional, nullable) — Latitude coordinate (-90 to 90) - `longitude` (double, optional, nullable) — Longitude coordinate (-180 to 180) ### PlannedArrival Planned arrival window for a stop - `start` (datetime, optional, nullable) — Earliest arrival time - `end` (datetime, optional, nullable) — Latest arrival time ### ActualStopTimes Actual stop times for tracking when arrival/departure occurred - `arrival_datetime` (datetime, optional, nullable) — Actual arrival timestamp - `departure_datetime` (datetime, optional, nullable) — Actual departure timestamp ### ValidationErrorLocItems ### ValidationErrorCtx ## Examples **Response** ```json { "id": "load_00000000-0000-0000-0000-000000000000", "load_number": "string", "organization_id": "org_00000000-0000-0000-0000-000000000000", "equipment_type": "VAN", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "tms_load_id": "string", "external_id": "string", "mode": "FTL", "load_status": "string", "tms_status": "string", "weight": 1.1, "distance": 1.1, "commodity": "string", "handling_unit_count": 1, "handling_unit_type": "string", "po_numbers": [ "string" ], "reference_numbers": [ { "value": "string", "type": "string" } ], "posted_rate": 1, "max_buy_rate": 1, "suggested_market_rate": 1, "length_feet": 1, "special_instructions": [ "string" ], "notes": "string", "is_posted": false, "last_posted_at": "2024-01-15T09:30:00Z", "last_unposted_at": "2024-01-15T09:30:00Z", "externally_posted_at": "2024-01-15T09:30:00Z", "temperature_setting_minimum": 1, "temperature_setting_maximum": 1, "temperature_run_type": "string", "last_reported_state": "string", "last_reported_city": "string", "last_reported_long": 1.1, "last_reported_lat": 1.1, "tms_carrier_id": "string", "carrier_name": "string", "hauling_carrier_id": "car_00000000-0000-0000-0000-000000000000", "hauling_carrier_name": "string", "hauling_carrier_mc_number": "string", "hauling_carrier_dot_number": "string", "carrier_completed_rate": 1.1, "customer_rate": 1.1, "margin": 1.1, "customer_name": "string", "tms_sales_rep_names": "string", "carrier_rep": { "type": "Driver", "first_name": "string", "last_name": "string", "phone": "string", "email": "string" }, "driver": { "type": "Driver", "first_name": "string", "last_name": "string", "phone": "string", "email": "string" }, "carrier_rep_user_id": "usr_00000000-0000-0000-0000-000000000000", "carrier_rep_user_name": "string", "carrier_rep_user_email": "string", "assigned_to_ai_agent": false, "stops": [ { "location": { "city": "string", "state": "string", "street": "string", "postal_code": "string", "country": "string", "company_name": "string", "county": "string", "latitude": 1.1, "longitude": 1.1 }, "id": "stop_00000000-0000-0000-0000-000000000000", "stop_number": 1, "is_pickup": true, "is_dropoff": true, "expected_date": "2024-01-15T09:30:00Z", "contact": { "type": "Driver", "first_name": "string", "last_name": "string", "phone": "string", "email": "string" }, "type": "Pickup", "planned": { "start": "2024-01-15T09:30:00Z", "end": "2024-01-15T09:30:00Z" }, "pickup_delivery_number": "string", "contacts": [ { "type": "Driver", "first_name": "string", "last_name": "string", "phone": "string", "email": "string" } ], "actual_stop_times": { "arrival_datetime": "2024-01-15T09:30:00Z", "departure_datetime": "2024-01-15T09:30:00Z" }, "carrier_eta": "2024-01-15T09:30:00Z", "reference_numbers": [ { "value": "string", "type": "string" } ], "notes": "string", "special_instructions": [ "string" ] } ], "context": {}, "custom_fields": {}, "offer_count": 0, "max_offer_amount": 1.1, "min_offer_amount": 1.1, "active_escalation_count": 0 } ``` **SDK Code** ```python import requests url = "https://tryenvoy.ai/api/v1/loads/load_id" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://tryenvoy.ai/api/v1/loads/load_id'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://tryenvoy.ai/api/v1/loads/load_id" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://tryenvoy.ai/api/v1/loads/load_id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://tryenvoy.ai/api/v1/loads/load_id") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://tryenvoy.ai/api/v1/loads/load_id', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://tryenvoy.ai/api/v1/loads/load_id"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://tryenvoy.ai/api/v1/loads/load_id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```