Appointment $confirm
The $confirm operation is currently in beta.
The $confirm operation confirms a held Appointment by atomically setting its status to booked and upgrading all busy-tentative Slot resources it references to busy in a single database transaction.
Booking Lifecycle
$confirm is the final step in a hold-then-book flow:
$find— Query available time slots$hold— Reserve a slot. Creates apendingAppointment andbusy-tentativeSlots$confirm— Confirm the hold. Transitions the Appointment tobookedand Slots tobusy
Use Cases
- Patient initiated booking: A patient can self-schedule a "pending" appointment; staff confirms when accepting it
- Staff approval workflow: A coordinator places a hold on behalf of a patient; a clinician or admin confirms
- Automated confirmation: Programmatically confirm a hold after an external step (e.g., payment or consent) completes
Invoke the $confirm operation
[base]/R4/Appointment/:id/$confirm
import { MedplumClient } from '@medplum/core';
import type { Bundle } from '@medplum/fhirtypes';
const medplum = new MedplumClient();
const bundle = await medplum.post<Bundle>(
medplum.fhirUrl('Appointment', 'my-appointment-id', '$confirm')
);
curl -X POST 'https://api.medplum.com/fhir/R4/Appointment/my-appointment-id/$confirm' \
-H "Authorization: Bearer MY_ACCESS_TOKEN"
Parameters
The appointment to confirm is identified by the id in the URL.
| Name | Type | Description | Required |
|---|---|---|---|
occurrences | code | For an occurrence of a recurring series, which occurrences to confirm: this (the default), this-and-following, or all. See Confirming a recurring series. | No |
Constraints
- The Appointment must have
status: pendingorstatus: proposed. All other statuses are rejected with HTTP 400 Bad Request. - All
Slotresources referenced byAppointment.slotmust exist and be readable by the caller. occurrences, when sent, must bethis,this-and-following, orall.
Output
Returns 200 OK with a Bundle of all updated resources:
- One
Appointmentwithstatus: booked - One
Slotper referenced slot that wasbusy-tentative(nowbusy). Slots already inbusystatus are returned unchanged.
When confirming several occurrences of a recurring series, the Bundle holds each booked Appointment followed by its Slots, in order of start.
Example Response
{
"resourceType": "Bundle",
"type": "transaction-response",
"entry": [
{
"resource": {
"resourceType": "Appointment",
"id": "my-appointment-id",
"status": "booked",
"start": "2026-03-10T09:00:00.000Z",
"end": "2026-03-10T10:00:00.000Z",
"participant": [
{ "actor": { "reference": "Practitioner/dr-smith" }, "status": "tentative" },
{ "actor": { "reference": "Patient/my-patient-id" }, "status": "accepted" }
],
"slot": [{ "reference": "Slot/my-slot-id" }]
}
},
{
"resource": {
"resourceType": "Slot",
"id": "my-slot-id",
"status": "busy",
"start": "2026-03-10T09:00:00.000Z",
"end": "2026-03-10T10:00:00.000Z",
"schedule": { "reference": "Schedule/dr-smith-schedule" }
}
}
]
}
Confirming a recurring series
An Appointment held as part of a recurring series
carries the series identifier that every occurrence shares. By default $confirm confirms only the
Appointment in the URL. The occurrences parameter confirms more of its series in the same call:
occurrences | Confirms |
|---|---|
this | Only this Appointment (the default) |
this-and-following | This Appointment and the occurrences of its series that start at or after it |
all | Every occurrence of its series |
curl -X POST 'https://api.medplum.com/fhir/R4/Appointment/my-appointment-id/$confirm' \
-H "Content-Type: application/fhir+json" \
-H "Authorization: Bearer MY_ACCESS_TOKEN" \
-d '{
"resourceType": "Parameters",
"parameter": [{ "name": "occurrences", "valueCode": "all" }]
}'
- Only occurrences that are
pendingorproposedare confirmed; others, such as ones already confirmed or cancelled, are left as they are. The Appointment in the URL must itself be confirmable, as withoutoccurrences. - Which occurrences follow this one is decided by their
start, not theirrecurrenceId. An Appointment without astartcan't be confirmed withthis-and-following. - Every occurrence is confirmed in one transaction, all or none: if any of them fails a check below, none is confirmed.
- At most 6 occurrences are confirmed at once, the most a series
$bookcreates. If more of the series would be confirmed, the request is refused with HTTP 400 Bad Request and none is. occurrencesother thanthisis refused for an Appointment outside a series. Check for the series identifier before offering to confirm more than one occurrence.
Confirmation Logic
$confirm performs the following steps atomically inside a database transaction, ensuring safety when concurrent scheduling requests are received.
- Reads the Appointment identified by the URL
id - Validates that the Appointment's
statusispendingorproposed - Loads any
HealthcareServicereferenced byAppointment.serviceTypeand validates that it is not inactive - Loads all
Slotresources listed inAppointment.slot - Updates any
busy-tentativeSlots tobusy - Sets the Appointment's
statustobookedand saves it - Returns the updated Appointment and Slots in a Bundle
Error Responses
Appointment Not Found
{
"resourceType": "OperationOutcome",
"issue": [{ "severity": "error", "code": "not-found", "details": { "text": "Not found" } }]
}
HTTP status: 404
Appointment Not in Confirmable State
{
"resourceType": "OperationOutcome",
"issue": [{ "severity": "error", "code": "conflict", "details": { "text": "Appointment cannot be confirmed in 'booked' status" } }]
}
HTTP status: 409
HealthcareService Inactive
A HealthcareService with active: false cannot be scheduled against. Appointments already booked for the service can still be canceled.
{
"resourceType": "OperationOutcome",
"issue": [{ "severity": "error", "code": "invalid", "details": { "text": "HealthcareService is inactive" } }]
}
HTTP status: 400
Referenced HealthcareService Not Found
Returned when a HealthcareService referenced by Appointment.serviceType has been deleted, or is not readable by the caller's access policy.
{
"resourceType": "OperationOutcome",
"issue": [{ "severity": "error", "code": "invalid", "details": { "text": "Loading HealthcareService failed" } }]
}
HTTP status: 400
Unknown occurrences
{
"resourceType": "OperationOutcome",
"issue": [{ "severity": "error", "code": "invalid", "details": { "text": "occurrences must be one of this, this-and-following, all" }, "expression": ["Parameters.occurrences"] }]
}
HTTP status: 400
Not Part of a Recurring Series
Returned for occurrences other than this when the Appointment has no series identifier.
{
"resourceType": "OperationOutcome",
"issue": [{ "severity": "error", "code": "invalid", "details": { "text": "Appointment is not part of a recurring series" }, "expression": ["Parameters.occurrences"] }]
}
HTTP status: 400
Referenced Slot Not Found
{
"resourceType": "OperationOutcome",
"issue": [{ "severity": "error", "code": "invalid", "details": { "text": "Loading slots failed" } }]
}
HTTP status: 400
Related
- Appointment
$hold- Place a hold on a slot (the preceding step) - Appointment
$cancel- Cancel an Appointment - Appointment
$find- Find available slots - Scheduling Overview - High-level scheduling concepts
AppointmentresourceSlotresource