# Missed Appointments V1 — Developer Guide

> **Reference:** [Missed Appointments (V1) — Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-appointment-management/missed-appointments-(v1))
If that path moves in Papidocs, search for **Missed Appointments (V1)** in the public API reference.


## What is a missed appointment?

A **MissedAppointmentV1** record is created by the system when a linked **AppointmentV1** is set to **`BROKEN`** or **`NO_SHOW`**. There is **no** `POST /v1/missedappointments` in the Public API; integrations create or change missed appointments indirectly by updating the **appointment** (see [Appointments V1 — Developer Guide](/publicapi/endpoints/appointments-v1)).

## `rescheduledOn` and rescheduling

### What `rescheduledOn` means

On **`MissedAppointmentV1`**, **`rescheduledOn`** is a **read-only** timestamp indicating **when** the linked appointment **left** a broken/no-show state (server-side side effect). It is **not** the same as the appointment’s **`start`** (scheduled slot).

### How to populate `rescheduledOn`

Use the **`appointmentId`** of the linked **`AppointmentV1`** on the missed record — that is the **`appointmentId`** in **`PUT /api/v1/appointments/{appointmentId}`** (not a different appointment, unless your workflow explicitly creates a new one):

1. **`PUT /api/v1/appointments/{appointmentId}`** — set **`status`** from **`BROKEN`** (or **`NO_SHOW`**) to any status **other than** **`BROKEN`** and **`NO_SHOW`** (for example **`CHAIR`**, **`CONFIRMED`**, etc.).
2. Optionally on the **same** or a **follow-up** `PUT`, send **`start`** and/or **`duration`** when the patient should be seen at a **new** time.


**`start` and `duration` are optional** on the status-changing `PUT`, but **strongly recommended** whenever you intend to **move** the visit to a new slot. If you send **only** `status` (for example `{ "status": "CHAIR" }`), the API **keeps** the appointment’s existing **`start`** and implied **`end`** unchanged—the appointment is no longer broken, but it remains at the **same** date/time until you update **`start`** (and **`duration`** if the length changes).

For full appointment validation, status values, and examples, see [Appointments V1 — Developer Guide](/publicapi/endpoints/appointments-v1).

### What not to do

**`PUT /api/v1/missedappointments/{missedAppointmentId}`** does **not** accept **`rescheduledOn`** or **`note`** in the request body for client updates; those fields are read-only on the resource and are not applied from JSON. Use the **appointments** `PUT` flow above to set **`rescheduledOn`** indirectly.

## GET — Bulk missed appointments

Returns missed appointments matching filter criteria.

### Recommended filters

Always narrow your query. Supported filter keys include:

| Filter | Supported operators |
|  --- | --- |
| `location.id` | `==`, `!=`, `->` |
| `start` | `>`, `<`, `>=`, `<=` |
| `patient.id` | `==`, `!=` |
| `operatory.id` | `==`, `!=`, `->` |
| `appointment.id` | `==` |


> See the endpoint reference for the full, up-to-date list of parameters and examples.


### Important notes

> **⚠️ Upcoming breaking change:** `location.id` (as a list of IDs or `["ALL"]`) will become a **required** filter. Omitting `location.id` may currently default to all locations for a transitional period.


> **⚠️ Date-limiting filter:** If you do not provide a date-limiting filter (such as `start` or `lastModified` where applicable), the API may apply one automatically. Behavior may vary by endpoint—check the official reference.


> **Rate limiting:** Missed appointment endpoints are rate limited. See [Rate limiting](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting) in the API Consumer Guide for details.


## Paginating with `lastId`

Same pattern as other bulk endpoints: use **`lastId`** with **`pageSize`** for efficient paging. Pass the **`id`** of the last record from the previous response as **`lastId`** on the next request until `data` is empty.

## GET — Missed appointment by ID

`GET /api/v1/missedappointments/{missedAppointmentId}` returns a single **`MissedAppointmentV1`**.

Optional query parameter **`responseFields`**: comma-separated field names, or **`ALL`**.

## PUT — Update missed appointment

`PUT /api/v1/missedappointments/{missedAppointmentId}` returns the updated **`MissedAppointmentV1`**.

Request body schema **`MissedAppointmentUpdateV1`**. Fields that are **accepted** from the client for this operation include:

| Field | Purpose |
|  --- | --- |
| `cancelledOn` | Optional cancellation timestamp (`date-time`). |
| `reasonCancelled` | Optional text (max 200 characters). |
| `status` | Optional. Values for this resource: **`NO_SHOW`**, **`BROKEN`**. |


Do **not** rely on sending **`rescheduledOn`** or **`note`** on this `PUT`; they are **read-only** on the model and are not updated from the request body.

Optional query parameter **`responseFields`**.

## DELETE — Missed appointment

> **⚠️ Caution:** Only call **DELETE** when you are **sure** you intend to remove the missed-appointment record. Deletion is **permanent** for that resource; there is no `POST` to recreate a missed appointment from the Public API. If you only meant to correct scheduling or status, use **`PUT /api/v1/appointments/{appointmentId}`** (and related flows) instead of deleting the missed appointment.


`DELETE /api/v1/missedappointments/{missedAppointmentId}` deletes that missed appointment. Success response describes deletion (see OpenAPI **`DeletedResult`**).

## Response structure

### Bulk GET — `MissedAppointmentBulkResponseWrapperV1`

| Field | Type | Description |
|  --- | --- | --- |
| `data` | array | Array of **`MissedAppointmentV1`** objects |
| `warnings` | array | Non-fatal warnings |
| `errors` | array | Errors when the request fails validation |
| `meta` | object | Pagination metadata where applicable |


### Single GET / PUT — `MissedAppointmentResponseWrapperV1`

| Field | Type | Description |
|  --- | --- | --- |
| `data` | object | Single **`MissedAppointmentV1`** |
| `warnings` | array | Non-fatal warnings |
| `errors` | array | Errors when the request fails validation |


### `MissedAppointmentV1` object (high level)

| Field | Type | Access | Description |
|  --- | --- | --- | --- |
| `id` | integer | read-only | Missed appointment identifier |
| `appointment` | object | read-only | Linked **`AppointmentV1`** |
| `start` | string | read-only | Start of the missed occurrence (`date-time`) |
| `duration` | integer | read-only | Duration in minutes |
| `status` | string | mixed | Response shows **`NO_SHOW`** or **`BROKEN`**; **`PUT`** may send `status` per **`MissedAppointmentUpdateV1`** |
| `operatory` | object | read-only | Linked operatory |
| `provider` | object | read-only | Linked provider |
| `patient` | object | read-only | Linked patient |
| `location` | object | read-only | Linked location |
| `other` | string | read-only | Additional text |
| `procedures` | string | read-only | Procedure summary |
| `cancelledOn` | string | read/write | Set via **`PUT`** body when allowed |
| `reasonCancelled` | string | read/write | Set via **`PUT`** body when allowed |
| `rescheduledOn` | string | read-only | Set by system when appointment leaves **`BROKEN`** / **`NO_SHOW`** |
| `note` | string | read-only | Note on the missed record (not client-writable on `PUT`) |


## Streaming API

For real-time changes to missed appointments, prefer the **Streaming API** over high-frequency polling of bulk GET.

## Errors and warnings reference

details
summary
strong
HTTP status code errors
— click to expand
These apply to all Missed Appointments V1 endpoints.

#### `400` — Bad Request

The request body or query parameters are invalid or cannot be processed.

#### `401` — Unauthorized

Authentication failed or was not provided. Send a valid Bearer token.

#### `403` — Forbidden

The token lacks scope. Bulk and GET-by-id require **`model:read`**; **`PUT`** and **`DELETE`** require **`model:write`**.

#### `404` — Not Found

No missed appointment exists for the given **`missedAppointmentId`** in your organization, or the path id is invalid.

#### `408` — Request Timeout

The server timed out. Retry with backoff.

#### `429` — Too Many Requests

Rate limit exceeded. Reduce request rate; see [Rate limiting](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting) in the API Consumer Guide.

#### `500` — Internal Server Error

Retry; contact support with correlation details if it persists.

details
summary
strong
Field-level validation
— click to expand
Validation errors are returned in the **`errors`** array on **`400`** responses. Exact messages depend on server validation; common cases include invalid **`filter`** syntax, invalid ids, or invalid **`date-time`** formats.

For **`reasonCancelled`**, respect the maximum length (**200** characters) as defined in **`MissedAppointmentUpdateV1`**.