> 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.

# Quickstart

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](https://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.

```bash
# Log in to get a bearer token
curl -X POST https://tryenvoy.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "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:

```bash
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:

```json
{
  "id": "load_550e8400-e29b-41d4-a716-446655440000",
  "load_number": "LD-2024-001",
  "equipment_type": "Van",
  "rate": 2500.00,
  "status": "pending"
}
```

## Step 3: View carrier matches

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

```bash
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:

```json
{
  "data": [
    {
      "carrier": {
        "id": "car_7f3a9c12-b8e4-4d5f-9a1c-2e8b6d4f0123",
        "name": "Midwest Express LLC",
        "mc_number": "MC-123456"
      },
      "match_score": 0.92
    },
    {
      "carrier": {
        "id": "car_9e2b1d45-c6f8-4a3e-8b7d-1f9c5e3a2468",
        "name": "Lone Star Freight Inc",
        "mc_number": "MC-789012"
      },
      "match_score": 0.87
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 47,
    "total_pages": 3
  }
}
```

## Step 4: Check outreach status

Monitor automated outreach activity for the load:

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

```json
{
  "data": [
    {
      "id": "otr_a3c7e912-f4b8-4d6a-9e2c-5b1d8f3a0789",
      "carrier_id": "car_7f3a9c12-b8e4-4d5f-9a1c-2e8b6d4f0123",
      "channel": "email",
      "status": "sent",
      "created_at": "2024-12-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 12,
    "total_pages": 1
  }
}
```

## Step 5: Review offers

Check offers that carriers have submitted on your load:

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

```json
{
  "data": [
    {
      "id": "ofr_b4d8f023-a5c9-4e7b-8f3d-6c2e9a1b4567",
      "carrier_id": "car_7f3a9c12-b8e4-4d5f-9a1c-2e8b6d4f0123",
      "amount": 2400.00,
      "status": "pending",
      "created_at": "2024-12-15T10:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 3,
    "total_pages": 1
  }
}
```

## Next steps

* Read about [pagination](/pages/pagination) for working with large result sets.
* Learn about [error handling](/pages/errors) to build resilient integrations.
* Understand [prefixed IDs](/pages/prefixed-ids) and how resource identifiers work.
* Explore the full [API Reference](/api-reference) for all available endpoints.