> 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. # Offer feed GET https://tryenvoy.ai/api/v1/offers/feed Every carrier offer created or changed after a point, oldest change first, for keeping a TMS in sync and reconciling missed webhooks. Start with `updated_since`, then pass `next_cursor` back as `cursor` while `has_more` is true. Store the last `next_cursor` to resume from there. `updated_since` is widened by 120 seconds and the last page's cursor may sit up to 120 seconds behind the newest row, so an offer committed late is replayed. An offer that changes again appears again too, so dedupe by `id` and keep the row with the latest `updated_at`. **Authentication:** Supports API key and bearer token authentication. Reference: https://docs.tryenvoy.ai/api-reference/endpoints/api/offer-feed-api-v-1-offers-feed-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 ### Query parameters - `updated_since` (datetime, optional, nullable) — Start from offers changed on or after this time, less a 120-second overlap (ISO-8601). Ignored with cursor. - `cursor` (string, optional, nullable) — Continue after a previous page's next_cursor - `status` (enum, optional, nullable) — Only offers in this status - Allowed values: `pending`, `accepted`, `rejected` - `tms_load_id` (string, optional, nullable) — Only offers on the load with this TMS id - `limit` (integer, optional, default: 100) — Page size ### Headers - `X-Organization-ID` (string, optional, nullable) ## Response ### 200 Successful Response - `data` (list of OfferResponse, required) — Rows in (timestamp, id) order, oldest first - `has_more` (boolean, required) — True when more rows follow; call again with next_cursor - `next_cursor` (string, optional, nullable) — Pass as `cursor` to continue after the last row returned. Present on every non-empty page, so a caller can store it and resume from exactly here next time. On the last page of a sync it may sit up to 120 seconds behind the newest row, so a row committed late is replayed on the next poll: dedupe by `id`. ## Errors ### 401 Unauthorized Error Not authenticated - missing or invalid token/API key - `any` ### 403 Forbidden Error Insufficient permissions for this operation - `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 ### OfferResponse v1 offer response - wraps domain OfferRead with prefixed IDs. - `id` (string, required) - `tms_load_id` (string, required) - `load_id` (string, required) - `offer_amount` (double, required) - `status` (enum, required) - Allowed values: `pending`, `accepted`, `rejected` - `source` (string, required) - `created_at` (datetime, required) - `updated_at` (datetime, required) - `carrier_id` (string, optional, nullable) - `contact_id` (string, optional, nullable) - `call_id` (string, optional, nullable) - `email_message_id` (string, optional, nullable) - `notes` (string, optional, nullable) - `channel` (enum, optional, nullable) — Which conversation produced the offer: voice (a call), email, or messaging (WhatsApp). Null when a rep or an API client entered it. - Allowed values: `voice`, `email`, `messaging` - `accepted_at` (datetime, optional, nullable) — When the load was booked on this offer - `created_by_id` (string, optional, nullable) - `updated_by_id` (string, optional, nullable) - `truck_number` (string, optional, nullable) - `trailer_number` (string, optional, nullable) - `driver_name` (string, optional, nullable) - `driver_phone` (string, optional, nullable) - `load_number` (string, optional, nullable) - `carrier` (CarrierResponse, optional, nullable) — v1 carrier response - wraps domain CarrierModel with prefixed IDs. - `contact_name` (string, optional, nullable) - `contact_phone` (string, optional, nullable) - `email_conversation_id` (string, optional, nullable) - `rep_name` (string, optional, nullable) ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (ValidationErrorCtx, optional) ### CarrierResponse v1 carrier response - wraps domain CarrierModel with prefixed IDs. - `id` (string, required) - `name` (string, required) - `mc_number` (string, optional, nullable) - `dot_number` (string, optional, nullable) - `email` (string, optional, nullable) - `phone` (string, optional, nullable) - `dispatcher_name` (string, optional, nullable) - `dispatcher_phone` (string, optional, nullable) - `dispatcher_email` (string, optional, nullable) - `is_active` (boolean, optional, default: true) - `tms_status` (string, optional, nullable) — Carrier status as reported by the source TMS (e.g. DNL). Read by the inbound email gate when the organization opts in to operational restriction notices for inactive carriers with this status. - `provider` (string, optional, nullable) - `ingestion_method` (string, optional, nullable) - `equipment_types` (list of enum, optional, nullable) - 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` - `insurance_expiration` (datetime, optional, nullable) - `w9_on_file` (boolean, optional, nullable) - `authorized_for_hire` (boolean, optional, nullable) - `on_time_pickup_pct` (double, optional, nullable) — On-time pickup percentage (0-100 scale) - `on_time_delivery_pct` (double, optional, nullable) — On-time delivery percentage (0-100 scale) - `tracking_compliance_pct` (double, optional, nullable) - `avg_response_time_min` (double, optional, nullable) - `total_loads_hauled` (integer, optional, nullable) - `is_onboarded` (boolean, optional, default: false) - `routing_guide_tier` (integer, optional, nullable) — Global routing-guide priority tier (1 = highest, 4 = lowest). None = untiered. - `lane_routing_guide_tier` (integer, optional, nullable) — Strongest routing-guide tier this carrier holds on the lane the list was filtered to (1 = highest). Null when the list has no lane filter, or the carrier is untiered on it. - `effective_routing_guide_tier` (integer, optional, nullable) — The tier that actually applies: `lane_routing_guide_tier` when set, else `routing_guide_tier`. Equal to the global tier on an unfiltered list. - `carrier_rep_user_id` (string, optional, nullable) - `carrier_rep_name` (string, optional, nullable) - `carrier_rep_email` (string, optional, nullable) - `is_verified` (boolean, optional, default: false) - `verified_date` (datetime, optional, nullable) - `compliance_status` (enum, optional) — The verdict of Envoy's most recent compliance check on the carrier: PASSED or BLOCKED, or UNVERIFIED when no check has run yet or the last check could not reach a result. - Allowed values: `PASSED`, `BLOCKED`, `UNVERIFIED` - `stop_contact_requested_at` (datetime, optional, nullable) — When the carrier last asked not to be contacted; Envoy stops contacting them - `tms_carrier_id` (string, optional, nullable) — The carrier's ID in your TMS - `last_verified_at` (datetime, optional, nullable) - `last_verified_provider` (string, optional, nullable) — Which compliance provider issued the most recent verification (e.g. Highway or MyCarrierPackets). Distinct from `provider`, which is the system the carrier record came from. Null when no verification has run, or when the provider was not recorded. - `created_at` (datetime, optional, nullable) - `updated_at` (datetime, optional, nullable) ### ValidationErrorLocItems - string - integer ### ValidationErrorCtx ## Examples **Response** ```json { "data": [ { "id": "ofr_00000000-0000-0000-0000-000000000000", "tms_load_id": "string", "load_id": "load_00000000-0000-0000-0000-000000000000", "offer_amount": 1.1, "status": "pending", "source": "string", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "carrier_id": "car_00000000-0000-0000-0000-000000000000", "contact_id": "con_00000000-0000-0000-0000-000000000000", "call_id": "call_00000000-0000-0000-0000-000000000000", "email_message_id": "string", "notes": "string", "channel": "voice", "accepted_at": "2024-01-15T09:30:00Z", "created_by_id": "usr_00000000-0000-0000-0000-000000000000", "updated_by_id": "usr_00000000-0000-0000-0000-000000000000", "truck_number": "string", "trailer_number": "string", "driver_name": "string", "driver_phone": "string", "load_number": "string", "carrier": { "id": "car_00000000-0000-0000-0000-000000000000", "name": "string", "mc_number": "string", "dot_number": "string", "email": "string", "phone": "string", "dispatcher_name": "string", "dispatcher_phone": "string", "dispatcher_email": "string", "is_active": true, "tms_status": "string", "provider": "string", "ingestion_method": "string", "equipment_types": [ "VAN" ], "insurance_expiration": "2024-01-15T09:30:00Z", "w9_on_file": true, "authorized_for_hire": true, "on_time_pickup_pct": 1.1, "on_time_delivery_pct": 1.1, "tracking_compliance_pct": 1.1, "avg_response_time_min": 1.1, "total_loads_hauled": 1, "is_onboarded": false, "routing_guide_tier": 1, "lane_routing_guide_tier": 1, "effective_routing_guide_tier": 1, "carrier_rep_user_id": "usr_00000000-0000-0000-0000-000000000000", "carrier_rep_name": "string", "carrier_rep_email": "string", "is_verified": false, "verified_date": "2024-01-15T09:30:00Z", "compliance_status": "PASSED", "stop_contact_requested_at": "2024-01-15T09:30:00Z", "tms_carrier_id": "string", "last_verified_at": "2024-01-15T09:30:00Z", "last_verified_provider": "string", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z" }, "contact_name": "string", "contact_phone": "string", "email_conversation_id": "string", "rep_name": "string" } ], "has_more": true, "next_cursor": "string" } ``` **SDK Code** ```python import requests url = "https://tryenvoy.ai/api/v1/offers/feed" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://tryenvoy.ai/api/v1/offers/feed'; 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/offers/feed" 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/offers/feed") 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/offers/feed") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://tryenvoy.ai/api/v1/offers/feed', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://tryenvoy.ai/api/v1/offers/feed"); 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/offers/feed")! 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() ```