Getting Started

Quickstart

Create a load, find carrier matches, and track offers in under 5 minutes.

This guide walks through the core API workflow: authenticate, create a load, find matching carriers, and monitor outreach and offers.

Prerequisites

You need an Envoy AI account. Sign up at tryenvoy.ai/app if you don’t have one.

Step 1: Get your API key

Create an API key from the dashboard, or use the API. If you already have a key, skip to Step 2.

$# Log in to get a bearer token
$curl -X POST https://tryenvoy.ai/api/v1/auth/login \
>  -H "Content-Type: application/json" \
>  -d '{
>    "email": "[email protected]",
>    "password": "your-password"
>  }'
$
$# Create an API key (use the access_token from above)
$curl -X POST https://tryenvoy.ai/api/v1/api-keys \
>  -H "Authorization: Bearer <access_token>" \
>  -H "Content-Type: application/json" \
>  -d '{"name": "Quickstart key"}'

Save the key value from the response. You will use it for all subsequent requests.

Step 2: Create a load

Post a freight load with origin, destination, and equipment details:

$curl -X POST https://tryenvoy.ai/api/v1/loads \
>  -H "X-API-Key: <your-api-key>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "load_number": "LD-2024-001",
>    "equipment_type": "Van",
>    "rate": 2500.00,
>    "stops": [
>      {
>        "type": "pickup",
>        "facility_name": "Chicago Distribution Center",
>        "address": {
>          "city": "Chicago",
>          "state": "IL",
>          "postal_code": "60601"
>        },
>        "scheduled_times": {
>          "start_datetime": "2024-12-15T08:00:00Z",
>          "end_datetime": "2024-12-15T12:00:00Z"
>        }
>      },
>      {
>        "type": "delivery",
>        "facility_name": "Dallas Warehouse",
>        "address": {
>          "city": "Dallas",
>          "state": "TX",
>          "postal_code": "75201"
>        },
>        "scheduled_times": {
>          "start_datetime": "2024-12-17T08:00:00Z",
>          "end_datetime": "2024-12-17T17:00:00Z"
>        }
>      }
>    ]
>  }'

The response includes the created load with its prefixed ID:

1{
2  "id": "load_550e8400-e29b-41d4-a716-446655440000",
3  "load_number": "LD-2024-001",
4  "equipment_type": "Van",
5  "rate": 2500.00,
6  "status": "pending"
7}

Step 3: View carrier matches

Use the load ID to find carriers with matching lane preferences and equipment:

$curl "https://tryenvoy.ai/api/v1/loads/load_550e8400-e29b-41d4-a716-446655440000/matches" \
>  -H "X-API-Key: <your-api-key>"

The response returns paginated carrier matches ranked by relevance:

1{
2  "data": [
3    {
4      "carrier": {
5        "id": "car_7f3a9c12-b8e4-4d5f-9a1c-2e8b6d4f0123",
6        "name": "Midwest Express LLC",
7        "mc_number": "MC-123456"
8      },
9      "match_score": 0.92
10    },
11    {
12      "carrier": {
13        "id": "car_9e2b1d45-c6f8-4a3e-8b7d-1f9c5e3a2468",
14        "name": "Lone Star Freight Inc",
15        "mc_number": "MC-789012"
16      },
17      "match_score": 0.87
18    }
19  ],
20  "pagination": {
21    "page": 1,
22    "page_size": 20,
23    "total_count": 47,
24    "total_pages": 3
25  }
26}

Step 4: Check outreach status

Monitor automated outreach activity for the load:

$curl "https://tryenvoy.ai/api/v1/loads/load_550e8400-e29b-41d4-a716-446655440000/outreaches" \
>  -H "X-API-Key: <your-api-key>"
1{
2  "data": [
3    {
4      "id": "otr_a3c7e912-f4b8-4d6a-9e2c-5b1d8f3a0789",
5      "carrier_id": "car_7f3a9c12-b8e4-4d5f-9a1c-2e8b6d4f0123",
6      "channel": "email",
7      "status": "sent",
8      "created_at": "2024-12-15T09:30:00Z"
9    }
10  ],
11  "pagination": {
12    "page": 1,
13    "page_size": 20,
14    "total_count": 12,
15    "total_pages": 1
16  }
17}

Step 5: Review offers

Check offers that carriers have submitted on your load:

$curl "https://tryenvoy.ai/api/v1/loads/load_550e8400-e29b-41d4-a716-446655440000/offers" \
>  -H "X-API-Key: <your-api-key>"
1{
2  "data": [
3    {
4      "id": "ofr_b4d8f023-a5c9-4e7b-8f3d-6c2e9a1b4567",
5      "carrier_id": "car_7f3a9c12-b8e4-4d5f-9a1c-2e8b6d4f0123",
6      "amount": 2400.00,
7      "status": "pending",
8      "created_at": "2024-12-15T10:15:00Z"
9    }
10  ],
11  "pagination": {
12    "page": 1,
13    "page_size": 20,
14    "total_count": 3,
15    "total_pages": 1
16  }
17}

Next steps