# Coaching session

Subscribe to `coaching_session` to follow a member's scheduled coaching sessions.

| `event_type` | Sent when |
| --- | --- |
| `coaching_session.created` | A session or a recurring series is scheduled. |
| `coaching_session.updated` | A session is changed, a series is changed from a date onward, or a session's attendance is recorded. |
| `coaching_session.canceled` | A session is canceled, or a series is canceled from a date onward. |

Each event comes in two shapes: one for a single session and one for a recurring series. The sections below show both.

## coaching_session.created

### One session

```json
{
  "event_type": "coaching_session.created",
  "data": {
    "medical_record_number": "3f2b8c1e-7a4d-4e9b-9c55-0d6a1f2e8b47",
    "plan_name": "Standard Plan",
    "session_id": "665f1c2ab7e4d90012a3f4c5",
    "scheduled_date": "2026-01-06T15:00:00.000Z",
    "end_time": "2026-01-06T15:30:00.000Z",
    "duration_minutes": 30,
    "meeting_url": "https://example.zoom.us/j/1234567890",
    "status": "scheduled",
    "is_recurring": false
  }
}
```

### Recurring series

One event is sent for the whole series, not one per session.

```json
{
  "event_type": "coaching_session.created",
  "data": {
    "medical_record_number": "3f2b8c1e-7a4d-4e9b-9c55-0d6a1f2e8b47",
    "plan_name": "Standard Plan",
    "recurrence_group_id": "0b9d6c1e-5d2a-4a57-8f43-2f6a9d3c7e10",
    "first_session_date": "2026-01-06T15:00:00.000Z",
    "duration_minutes": 30,
    "meeting_url": "https://example.zoom.us/j/1234567890",
    "is_recurring": true,
    "recurrence_rule": {
      "frequency": "weekly",
      "day_of_week": 2,
      "time_utc": "15:00",
      "end_date": "2026-06-30T00:00:00.000Z"
    }
  }
}
```

| Field | Type | Sent for | Description |
| --- | --- | --- | --- |
| `medical_record_number` | string (UUID) | Both | The member's medical record number. |
| `plan_name` | string | Both | The member's plan. Optional. |
| `is_recurring` | boolean | Both | `false` for one session, `true` for a series. Check this first. |
| `duration_minutes` | number | Both | The scheduled length. |
| `meeting_url` | string | Both | The video link. An empty string when there is none. |
| `session_id` | string | One session | The session's ID. |
| `scheduled_date` | string (date-time) | One session | The scheduled start time. |
| `end_time` | string (date-time) | One session | The scheduled end time. |
| `status` | string | One session | `scheduled`, `completed`, `canceled` or `no-show`. |
| `recurrence_group_id` | string | Series | The series ID. |
| `first_session_date` | string (date-time) | Series | The start time of the first session. |
| `recurrence_rule` | object or null | Series | How the series repeats. See [Recurrence rule](#recurrence-rule). |

To refer to one session in a series, use `recurrence_group_id` and the session's date.

## coaching_session.updated

### One session

```json
{
  "event_type": "coaching_session.updated",
  "data": {
    "medical_record_number": "3f2b8c1e-7a4d-4e9b-9c55-0d6a1f2e8b47",
    "plan_name": "Standard Plan",
    "session_id": "665f1c2ab7e4d90012a3f4c5",
    "recurrence_group_id": null,
    "scheduled_date": "2026-01-06T16:00:00.000Z",
    "end_time": "2026-01-06T16:30:00.000Z",
    "duration_minutes": 30,
    "status": "scheduled"
  }
}
```

### A series, from a date onward

Sent when every future session in a series is changed. Check for `"scope": "future"`.

```json
{
  "event_type": "coaching_session.updated",
  "data": {
    "medical_record_number": "3f2b8c1e-7a4d-4e9b-9c55-0d6a1f2e8b47",
    "plan_name": "Standard Plan",
    "recurrence_group_id": "0b9d6c1e-5d2a-4a57-8f43-2f6a9d3c7e10",
    "scope": "future",
    "effective_from": "2026-02-03T16:00:00.000Z",
    "duration_minutes": 30,
    "recurrence_rule": {
      "time_utc": "16:00",
      "day_of_week": 2
    }
  }
}
```

| Field | Type | Sent for | Description |
| --- | --- | --- | --- |
| `medical_record_number` | string (UUID) | Both | The member's medical record number. |
| `plan_name` | string | Both | The member's plan. Optional. |
| `duration_minutes` | number | Both | The scheduled length. |
| `recurrence_group_id` | string or null | Both | The series ID. `null` when the session is not part of a series. |
| `session_id` | string | One session | The session's ID. |
| `scheduled_date` | string (date-time) | One session | The scheduled start time after the change. |
| `end_time` | string (date-time) | One session | The scheduled end time after the change. |
| `status` | string | One session | `scheduled`, `completed`, `canceled` or `no-show`. |
| `scope` | string | Series | Always `future`. |
| `effective_from` | string (date-time) | Series | The first session the change applies to. |
| `recurrence_rule` | object or null | Series | The new time and day. Holds `time_utc` and `day_of_week` only. |

### Attendance

When a coach writes a check-in or no-show note, we match it to the nearest scheduled session and set that session's `status` to `completed` or `no-show`. If the status changes, a one-session `coaching_session.updated` is sent.

## coaching_session.canceled

Cancel events do not include `medical_record_number` or `plan_name`. Match them by `session_id` or `recurrence_group_id`.

### One session

```json
{
  "event_type": "coaching_session.canceled",
  "data": {
    "session_id": "665f1c2ab7e4d90012a3f4c5",
    "recurrence_group_id": null,
    "canceled_date": "2026-01-06T16:00:00.000Z"
  }
}
```

### A series, from a date onward

```json
{
  "event_type": "coaching_session.canceled",
  "data": {
    "recurrence_group_id": "0b9d6c1e-5d2a-4a57-8f43-2f6a9d3c7e10",
    "scope": "future",
    "effective_from": "2026-03-03T16:00:00.000Z",
    "canceled_count": 10
  }
}
```

| Field | Type | Sent for | Description |
| --- | --- | --- | --- |
| `recurrence_group_id` | string or null | Both | The series ID. `null` when the session is not part of a series. |
| `session_id` | string | One session | The canceled session's ID. |
| `canceled_date` | string (date-time) | One session | The scheduled start time of the canceled session. |
| `scope` | string | Series | Always `future`. |
| `effective_from` | string (date-time) | Series | Sessions from this time onward are canceled. |
| `canceled_count` | number | Series | How many sessions were canceled. |

## Recurrence rule

| Field | Type | Description |
| --- | --- | --- |
| `frequency` | string | `weekly`, `biweekly` or `monthly`. Sent on `created` only. |
| `day_of_week` | number | `0` is Sunday, `6` is Saturday. |
| `time_utc` | string | Start time in UTC, as `HH:mm`. |
| `end_date` | string (date-time) | When the series ends. Sent on `created` only. |

## JSON Schemas

- [`coaching_session.created`](https://developers.youareaccountable.com/schemas/coaching_session.created.json)
- [`coaching_session.updated`](https://developers.youareaccountable.com/schemas/coaching_session.updated.json)
- [`coaching_session.canceled`](https://developers.youareaccountable.com/schemas/coaching_session.canceled.json)
