## Enroll a contact

`POST /enroll-flow`

Starts a Workflow run for the given contact. The first step executes immediately. The response includes `runId` and the `pb_line_id` pinned to the run.

Because the first step runs before the response is written, the returned `status` is the state _after_ that step. A run that begins with a wait comes back `SLEEPING`, and one that begins by asking a question comes back `WAITING_REPLY` — `ACTIVE` is the exception, not the rule. Statuses are uppercase: `ACTIVE`, `SLEEPING`, `WAITING_REPLY`, `COMPLETED`, `CANCELLED`, `FAILED`.

### Request body

- `flowId` (string (UUID), required) — The Workflow id, as returned by GET /get-flows. An opaque UUID string — do not parse it. Must be 1 to 64 characters.

- `phoneNumber` (string, required) — The contact's phone number. Accepts many formats — normalized to E.164.

- `pb_line_id` (string (UUID)) — Optional. Line to send from (lineId from GET /get-lines). When omitted, a line is selected automatically and pinned for the entire run.

### Status codes

- **400** — Invalid phone number, invalid pb_line_id, or no available lines
- **403** — Contact has opted out
- **404** — Flow not found or not published, or line not found
- **409** — An active run already exists for this contact in this flow

**Request — cURL**

```bash
curl -X POST https://api.tryprojectblue.com/enroll-flow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flowId": "6f1c2a7e-9d4b-4c31-8a52-1e7f0b3d9c84",
    "phoneNumber": "+16025551234",
    "pb_line_id": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5"
  }'
```

**Response — 200 OK**

```json
{
  "success": true,
  "runId": 4182,
  "status": "SLEEPING",
  "currentNodeId": "node_wait_1",
  "pb_line_id": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5"
}
```

**Response — 400**

```json
{
  "error": "Invalid flowId"
}
```

**Response — 403**

```json
{
  "error": "Contact is opted out / blocked"
}
```

**Response — 404**

```json
{
  "error": "Flow not found or not published"
}
```

**Response — 409**

```json
{
  "error": "An active run already exists for this contact in this flow"
}
```