Initiate carrier outreach

curl -X POST https://tryenvoy.ai/api/v1/outreaches \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "carrier_id": "car_9f8b7c6d-1234-4a56-b789-0a1b2c3d4e5f",
  "load_id": "load_1a2b3c4d-5678-4e90-b123-4f5e6d7c8b9a"
}'

1	{
2	"id": "otr_4e5f6a7b-89c0-4d1e-9f23-4567b8c9d0e1",
3	"carrier": {
4	"id": "car_9f8b7c6d-1234-4a56-b789-0a1b2c3d4e5f",
5	"name": "Swift Logistics",
6	"mc_number": "MC123456",
7	"dot_number": "DOT654321",
8	"email": "[email protected]",
9	"phone": "+1-555-123-4567",
10	"dispatcher_name": "Jane Doe",
11	"dispatcher_phone": "+1-555-987-6543",
12	"dispatcher_email": "[email protected]",
13	"is_active": true,
14	"provider": "EnvoyAI",
15	"ingestion_method": "API",
16	"equipment_types": [
17	"VAN",
18	"REEFER"
19	],
20	"insurance_expiration": "2024-12-31T23:59:59Z",
21	"w9_on_file": true,
22	"authorized_for_hire": true,
23	"on_time_pickup_pct": 95.5,
24	"on_time_delivery_pct": 97.2,
25	"tracking_compliance_pct": 92.8,
26	"avg_response_time_min": 15.3,
27	"total_loads_hauled": 1240,
28	"is_onboarded": true,
29	"carrier_rep_user_id": "usr_7a8b9c0d-1234-4e56-b789-0a1b2c3d4e5f",
30	"carrier_rep_name": "John Smith",
31	"carrier_rep_email": "[email protected]",
32	"is_verified": true,
33	"verified_date": "2023-11-01T10:00:00Z",
34	"created_at": "2020-05-15T08:30:00Z",
35	"updated_at": "2024-04-20T14:45:00Z"
36	},
37	"load_id": "load_1a2b3c4d-5678-4e90-b123-4f5e6d7c8b9a",
38	"modality": "call",
39	"direction": "outbound",
40	"created_at": "2024-04-25T09:15:00Z",
41	"load_number": "LD123456789",
42	"status": "completed",
43	"error_reason": "",
44	"carrier_engaged": true,
45	"is_automated": false,
46	"call_id": "call_0a1b2c3d-4e5f-6789-abcd-ef0123456789",
47	"conversation_id": "conv_12345678-9abc-def0-1234-56789abcdef0"
48	}

Initiate an outbound carrier outreach (call or email). Validates outreach limits and load data before initiating.

Authentication: Supports API key and bearer token authentication.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

X-Organization-IDstring or nullOptional

Request

This endpoint expects an object.

carrier_idstringRequiredformat: "uuid"

Carrier UUID to contact

load_idstringRequiredformat: "uuid"

Load UUID for the outreach

modalityenumOptionalDefaults to call

Outreach channel: ‘call’ to initiate a voice call, ‘email’ to start an email negotiation

contact_idstring or nullOptionalformat: "uuid"

Specific contact UUID. If omitted, selects by priority.

Response

Successful Response

idstringformat: "^otr_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"

carrierobject

v1 carrier response - wraps domain CarrierModel with prefixed IDs.

load_idstringformat: "^load_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"

modalityenum

Communication channel: call or email

directionenum

Direction: inbound or outbound

created_atdatetime

load_numberstring or null

statusenumDefaults to completed

Async-execution lifecycle. Outbound outreaches initiated via the async path move pending → active → completed|failed; inbound and legacy sync paths are written as completed.

error_reasonstring or null

Terminal failure detail when status=‘failed’

carrier_engagedboolean or null

is_automatedbooleanDefaults to false

True if initiated by the automated outreach worker (Ellie), not a manual rep action.

call_idstringformat: "^call_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"

conversation_idstring or null

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

502

Bad Gateway Error