Skip to content

Missed Appointments V1 — Developer Guide

Reference: Missed Appointments (V1) — Endpoint Documentation
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).


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.

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.

Always narrow your query. Supported filter keys include:

FilterSupported 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 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:

FieldPurpose
cancelledOnOptional cancellation timestamp (date-time).
reasonCancelledOptional text (max 200 characters).
statusOptional. 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

FieldTypeDescription
dataarrayArray of MissedAppointmentV1 objects
warningsarrayNon-fatal warnings
errorsarrayErrors when the request fails validation
metaobjectPagination metadata where applicable

Single GET / PUT — MissedAppointmentResponseWrapperV1

FieldTypeDescription
dataobjectSingle MissedAppointmentV1
warningsarrayNon-fatal warnings
errorsarrayErrors when the request fails validation

MissedAppointmentV1 object (high level)

FieldTypeAccessDescription
idintegerread-onlyMissed appointment identifier
appointmentobjectread-onlyLinked AppointmentV1
startstringread-onlyStart of the missed occurrence (date-time)
durationintegerread-onlyDuration in minutes
statusstringmixedResponse shows NO_SHOW or BROKEN; PUT may send status per MissedAppointmentUpdateV1
operatoryobjectread-onlyLinked operatory
providerobjectread-onlyLinked provider
patientobjectread-onlyLinked patient
locationobjectread-onlyLinked location
otherstringread-onlyAdditional text
proceduresstringread-onlyProcedure summary
cancelledOnstringread/writeSet via PUT body when allowed
reasonCancelledstringread/writeSet via PUT body when allowed
rescheduledOnstringread-onlySet by system when appointment leaves BROKEN / NO_SHOW
notestringread-onlyNote on the missed record (not client-writable on PUT)

StreamAPI Webhooks

For real-time changes to missed appointments, prefer StreamAPI webhooks (SNS) over high-frequency polling of bulk GET.


Errors and warnings reference

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 in the API Consumer Guide.

500 — Internal Server Error

Retry; contact support with correlation details if it persists.


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.