# Enroll a trainee in a journey

`POST https://api.coach-platform.com/api/public/journeys/{journeyId}/enroll`

Enroll one trainee into an active journey. Identify them with traineeId (their active coaching period is used) or with escortId to pick a specific coaching period. A trainee already enrolled in another journey returns 409 unless replaceExisting is true. Enrollments are limited to one per second per coach, so space out loops that enroll many trainees.

- Resource: Journeys
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/post-journeys-journey-id-enroll
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `journeyId` | string | Yes |   |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | string | No | Optional. Send a unique key (e.g. a UUID) to make this POST safe to retry. The same key within 24h returns the original result instead of creating a duplicate. |

## Request body

Content type: `application/json`. Required.

| Field | Type | Required | Description |
|---|---|---|---|
| `traineeId` | string | No | The trainee to enroll, resolved to their active coaching period. Send this or escortId. |
| `escortId` | string | No | The coaching period to enroll. Send this or traineeId when you need a specific one. |
| `startDateShiftDays` | integer | No | Shift the journey start by this many days. Negative values start it in the past, so earlier steps fire immediately. |
| `startAtStepId` | string | No | Begin at this step instead of the first one. |
| `replaceExisting` | boolean | No | Cancel the trainee's current enrollment in another journey instead of returning 409. |

## Responses

| Status | Description |
|---|---|
| `201` Created |  |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `404` Not Found |  |
| `409` Conflict |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 201 Created

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object |   |
| `warnings` | object[] | Non-fatal problems with follow-up writes. The resource was created, but each listed field was not applied. |
| `warnings[].field` | string |   |
| `warnings[].message` | string |   |

Example:

```json
{
  "data": {},
  "warnings": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}
```

### Error responses 400, 401, 403, 404, 409, 429, 500

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `error` | object |   |
| `error.code` | string |   |
| `error.message` | string |   |
| `error.fix` | string \| null |   |
| `error.details` | object \| null |   |
| `error.retryAfterMs` | number \| null |   |

Example:

```json
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
```

## Examples

### cURL

```bash
curl --request POST \
  --url 'https://api.coach-platform.com/api/public/journeys/<journeyId>/enroll' \
  --header 'Authorization: Bearer cp_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "traineeId": "<string>"
}'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/journeys/<journeyId>/enroll', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cp_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "traineeId": "<string>"
  }),
});

const data = await response.json();
```

## Related endpoints

- [List journeys](https://www.coach-platform.com/docs/api/reference/get-journeys/index.md): `GET /api/public/journeys`. List customer journeys (automation templates) with search and pagination, including how many trainees are actively enrolled in each.
- [Create a journey](https://www.coach-platform.com/docs/api/reference/post-journeys/index.md): `POST /api/public/journeys`. Create a customer journey, optionally with its ordered steps.
- [List journey enrollments](https://www.coach-platform.com/docs/api/reference/get-journeys-enrollments/index.md): `GET /api/public/journeys/enrollments`. List trainee enrollments across journeys, filterable by journey, escort and status, with trainee, escort and journey resolved.
- [Get a journey](https://www.coach-platform.com/docs/api/reference/get-journeys-journey-id/index.md): `GET /api/public/journeys/{journeyId}`. Get a single customer journey with its full step structure: triggers, timing and the actions each step runs.
- [Update a journey](https://www.coach-platform.com/docs/api/reference/patch-journeys-journey-id/index.md): `PATCH /api/public/journeys/{journeyId}`. Update a customer journey's settings and steps.
- [Get journey analytics](https://www.coach-platform.com/docs/api/reference/get-journeys-journey-id-analytics/index.md): `GET /api/public/journeys/{journeyId}/analytics`. Enrollment and completion statistics for a single customer journey.
- [Get a trainee's journey progress](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-journey-progress/index.md): `GET /api/public/trainees/{traineeId}/journey-progress`. Where a trainee stands in their customer journey(s): current effective day and week, completed versus upcoming steps, and each journey's status.
- Previous: [Get journey analytics](https://www.coach-platform.com/docs/api/reference/get-journeys-journey-id-analytics/index.md): `GET /api/public/journeys/{journeyId}/analytics`. Enrollment and completion statistics for a single customer journey.
- Next: [Get a trainee's journey progress](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-journey-progress/index.md): `GET /api/public/trainees/{traineeId}/journey-progress`. Where a trainee stands in their customer journey(s): current effective day and week, completed versus upcoming steps, and each journey's status.