# Add the same private coach note to up to 500 coaching periods at once

`POST https://api.coach-platform.com/api/public/escorts/notes/bulk`

Add the same private coach note to up to 500 coaching periods at once. Every escort must belong to the coach and be reachable by this key, otherwise nothing is written and 403 or 404 is returned. Canceled coaching periods return 422.

- Resource: Escorts
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/post-escorts-notes-bulk
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## 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 |
|---|---|---|---|
| `escortIds` | string[] | Yes | Between 1 and 500 escort ids Minimum items: `1`. Maximum items: `500`. |
| `title` | string | No | Short note title. |
| `content` | string | Yes | Note body (plain text). Required. Minimum length: `1`. |
| `pinned` | boolean | No | true keeps the note at the top of each list. Defaults to false. |

## Responses

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

### 200 OK

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object |   |
| `data.updatedEscorts` | integer | How many coaching periods received the note. |

Example:

```json
{
  "data": {
    "updatedEscorts": 123
  }
}
```

### 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/escorts/notes/bulk' \
  --header 'Authorization: Bearer cp_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "escortIds": [
    "<string>"
  ],
  "content": "<string>"
}'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/escorts/notes/bulk', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cp_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "escortIds": [
      "<string>"
    ],
    "content": "<string>"
  }),
});

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

## Related endpoints

- [Get a coaching period](https://www.coach-platform.com/docs/api/reference/get-escorts-escort-id/index.md): `GET /api/public/escorts/{escortId}`. Get a coaching period by id.
- [Update a coaching period](https://www.coach-platform.com/docs/api/reference/patch-escorts-escort-id/index.md): `PATCH /api/public/escorts/{escortId}`. Update a coaching period.
- [Cancel a coaching period](https://www.coach-platform.com/docs/api/reference/delete-escorts-escort-id/index.md): `DELETE /api/public/escorts/{escortId}`. Cancel a coaching period.
- [Start a coaching period](https://www.coach-platform.com/docs/api/reference/post-escorts/index.md): `POST /api/public/escorts`. Start a new coaching period (escort) for a trainee.
- [List the private coach notes on a coaching period, pinned notes…](https://www.coach-platform.com/docs/api/reference/get-escorts-escort-id-notes/index.md): `GET /api/public/escorts/{escortId}/notes`. List the private coach notes on a coaching period, pinned notes first and then newest first.
- [Add a private coach note to a coaching period, with an optional…](https://www.coach-platform.com/docs/api/reference/post-escorts-escort-id-notes/index.md): `POST /api/public/escorts/{escortId}/notes`. Add a private coach note to a coaching period, with an optional title and pin.
- [Edit a coach note on a coaching period](https://www.coach-platform.com/docs/api/reference/patch-escorts-escort-id-notes-note-id/index.md): `PATCH /api/public/escorts/{escortId}/notes/{noteId}`. Edit a coach note on a coaching period.
- [Delete a coach note from a coaching period](https://www.coach-platform.com/docs/api/reference/delete-escorts-escort-id-notes-note-id/index.md): `DELETE /api/public/escorts/{escortId}/notes/{noteId}`. Delete a coach note from a coaching period.
- Previous: [Add a private coach note to a coaching period, with an optional…](https://www.coach-platform.com/docs/api/reference/post-escorts-escort-id-notes/index.md): `POST /api/public/escorts/{escortId}/notes`. Add a private coach note to a coaching period, with an optional title and pin.
- Next: [Edit a coach note on a coaching period](https://www.coach-platform.com/docs/api/reference/patch-escorts-escort-id-notes-note-id/index.md): `PATCH /api/public/escorts/{escortId}/notes/{noteId}`. Edit a coach note on a coaching period.
