> 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. # Create a carrier POST https://tryenvoy.ai/api/v1/carriers Content-Type: application/json Create or update one carrier, with compliance and fraud checking. A carrier matching on tms_carrier_id, MC, DOT or name is updated: 201 when the carrier was created, 200 when updated. **Authentication:** Supports API key and bearer token authentication. Reference: https://docs.tryenvoy.ai/api-reference/endpoints/carriers/create ## 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 ### Headers - `X-Organization-ID` (string, optional, nullable) - `Idempotency-Key` (string, optional) — 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. ### Body (application/json) This endpoint expects a CarrierCreateRequest. - `name` (string, required) — Carrier company name - `tms_carrier_id` (string, optional, nullable) — Your TMS's ID for the carrier; Envoy matches updates on it first - `mc_number` (string, optional, nullable) — MC number - `dot_number` (string, optional, nullable) — DOT number - `email` (string, optional, nullable) — Primary email - `phone` (string, optional, nullable) — Primary phone (any common format, stored as E.164) - `dispatcher_name` (string, optional, nullable) — Dispatcher name - `dispatcher_phone` (string, optional, nullable) — Dispatcher phone (any common format, stored as E.164) - `dispatcher_email` (string, optional, nullable) — Dispatcher email - `contacts` (list of CarrierContactInput, optional, nullable) — Typed contacts list - `on_time_delivery_pct` (double, optional, nullable) — On-time delivery percentage (0-100 scale) - `on_time_pickup_pct` (double, optional, nullable) — On-time pickup percentage (0-100 scale) - `total_loads_hauled` (integer, optional, nullable) — Total loads hauled - `is_onboarded` (boolean, optional, default: false) — Whether carrier is onboarded - `is_active` (boolean, optional, default: true) — Whether the carrier is active. False creates the carrier disabled, or disables it if it already exists (e.g. the source TMS flags it do-not-load). True never re-enables an existing carrier; use the enable endpoint for that. - `tms_status` (string, optional, nullable) — Carrier status as reported by the source TMS (e.g. DNL). Stored as sent; the latest value wins. Read by the inbound email gate when the organization opts in to operational restriction notices for inactive carriers with this status. - `equipment_types` (list of enum, optional, nullable) — Equipment types this carrier can haul - 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` - `carrier_rep_name` (string, optional, nullable) — Carrier rep owner full name - `carrier_rep_email` (string, optional, nullable) — Carrier rep owner email ## Response ### 200 An existing carrier was updated - `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) ### 201 Successful Response - `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) ## Errors ### 401 Unauthorized Error Not authenticated - missing or invalid token/API key - `any` ### 403 Forbidden Error Insufficient permissions for this operation - `any` ### 409 Conflict Error `idempotency_key_in_progress`: a request with this Idempotency-Key is still running; retry later - `any` ### 422 Unprocessable Entity Error Validation Error; or `idempotency_key_reused`: this Idempotency-Key was already used for a different request - `detail` (list of ValidationError, optional) ### 429 Too Many Requests Error Rate limit exceeded - see Retry-After header - `any` ## Types ### CarrierContactInput Typed contact entry for carrier ingestion. - `contact_type` (enum, required) - Allowed values: `CARRIER`, `DISPATCHER`, `DRIVER`, `TENDERING`, `QUOTING`, `OTHER` - `name` (string, optional, nullable) — Contact name - `phone` (string, optional, nullable) — Contact phone (any common format, stored as E.164) - `email` (string, optional, nullable) — Contact email - `equipment_type` (enum, optional, nullable) — Equipment type this contact handles - 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` ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (ValidationErrorCtx, optional) ### ValidationErrorLocItems ### ValidationErrorCtx ## Examples ### Example 1 **Request** ```json { "name": "string" } ``` **Response** ```json { "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" } ``` **SDK Code** ```python import requests url = "https://tryenvoy.ai/api/v1/carriers" payload = { "name": "string" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://tryenvoy.ai/api/v1/carriers'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"string"}' }; 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" "strings" "net/http" "io" ) func main() { url := "https://tryenvoy.ai/api/v1/carriers" payload := strings.NewReader("{\n \"name\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") 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/carriers") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://tryenvoy.ai/api/v1/carriers") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"string\"\n}") .asString(); ``` ```php request('POST', 'https://tryenvoy.ai/api/v1/carriers', [ 'body' => '{ "name": "string" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://tryenvoy.ai/api/v1/carriers"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["name": "string"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://tryenvoy.ai/api/v1/carriers")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data 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() ``` ### Example 2 **Request** ```json { "name": "string" } ``` **Response** ```json { "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" } ``` **SDK Code** ```python import requests url = "https://tryenvoy.ai/api/v1/carriers" payload = { "name": "string" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://tryenvoy.ai/api/v1/carriers'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"string"}' }; 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" "strings" "net/http" "io" ) func main() { url := "https://tryenvoy.ai/api/v1/carriers" payload := strings.NewReader("{\n \"name\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") 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/carriers") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://tryenvoy.ai/api/v1/carriers") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"string\"\n}") .asString(); ``` ```php request('POST', 'https://tryenvoy.ai/api/v1/carriers', [ 'body' => '{ "name": "string" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://tryenvoy.ai/api/v1/carriers"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["name": "string"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://tryenvoy.ai/api/v1/carriers")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data 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() ```