# Schedule a meeting

`POST https://api.coach-platform.com/api/public/meetings`

Schedule a meeting. "type" is the location (Online or In person). "meetingType" is the format (Individual or Group).

- Resource: Meetings
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/post-meetings
- 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 |
|---|---|---|---|
| `title` | string | Yes |   |
| `startDate` | string | Yes | ISO date-time |
| `endDate` | string | Yes | ISO date-time |
| `duration` | number | No | Minutes (optional) |
| `type` | string | Yes | Allowed values: `Online`, `In person`. |
| `meetingType` | string | No | Allowed values: `Individual`, `Group`. |
| `onlineLink` | string | No | Zoom/Meet URL |
| `address` | string | No | Physical address |
| `notes` | string | No |   |
| `trainees` | string[] | No | Array of trainee ids Maximum items: `500`. |
| `capacity` | number | No | For group meetings |

## 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 |   |
| `data.id` | string |   |
| `data.coach` | string |   |
| `data.title` | string |   |
| `data.startDate` | string<date-time> |   |
| `data.endDate` | string<date-time> |   |
| `data.duration` | number |   |
| `data.type` | string | Allowed values: `Online`, `In person`. |
| `data.meetingType` | string | Allowed values: `Individual`, `Group`. |
| `data.onlineLink` | string |   |
| `data.address` | string |   |
| `data.notes` | string |   |
| `data.status` | string |   |
| `data.capacity` | number |   |
| `data.trainees` | object[] | Meeting attendees. email and phoneNumber are returned only when the key also has the trainees:read scope. |
| `data.trainees[].id` | string |   |
| `data.trainees[].name` | string |   |
| `data.trainees[].email` | string |   |
| `data.trainees[].phoneNumber` | string |   |
| `data.createdAt` | string<date-time> |   |
| `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": {
    "id": "<string>",
    "coach": "<string>",
    "title": "<string>",
    "startDate": "<date-time>",
    "endDate": "<date-time>",
    "duration": 123,
    "type": "Online",
    "meetingType": "Individual",
    "onlineLink": "<string>",
    "address": "<string>",
    "notes": "<string>",
    "status": "<string>",
    "capacity": 123,
    "trainees": [
      {
        "id": "<string>",
        "name": "<string>",
        "email": "<string>",
        "phoneNumber": "<string>"
      }
    ],
    "createdAt": "<date-time>"
  },
  "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/meetings' \
  --header 'Authorization: Bearer cp_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "<string>",
  "startDate": "<string>",
  "endDate": "<string>",
  "type": "Online"
}'
```

### JavaScript (fetch)

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

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

## Related endpoints

- [List meetings](https://www.coach-platform.com/docs/api/reference/get-meetings/index.md): `GET /api/public/meetings`. List meetings in a time window.
- [Get a meeting](https://www.coach-platform.com/docs/api/reference/get-meetings-meeting-id/index.md): `GET /api/public/meetings/{meetingId}`. Get a meeting by id.
- [Update a meeting](https://www.coach-platform.com/docs/api/reference/patch-meetings-meeting-id/index.md): `PATCH /api/public/meetings/{meetingId}`. Update a meeting (time, title, attendees, notes, status).
- [Delete a meeting](https://www.coach-platform.com/docs/api/reference/delete-meetings-meeting-id/index.md): `DELETE /api/public/meetings/{meetingId}`. Delete a meeting permanently.
- Previous: [List meetings](https://www.coach-platform.com/docs/api/reference/get-meetings/index.md): `GET /api/public/meetings`. List meetings in a time window.
- Next: [Get a meeting](https://www.coach-platform.com/docs/api/reference/get-meetings-meeting-id/index.md): `GET /api/public/meetings/{meetingId}`. Get a meeting by id.