Change Appointment Status

Apply an allowed appointment status transition using the expected version and record its attributed history.

Scope: agenda:appointments:write
Credentials: a person's access token only; API keys and client-credentials tokens get 403
Effect: writes
Limits: request body up to 256 KB, response up to 8 MB
CLI: arbol agenda appointments change-status · not available on MCP

POST

https://api.getarbol.com/v1/agenda/appointments/{appointmentId}/change-status

Authorization

Authorization
string
required
Bearer <token>, where the token is a person's access token with the scope agenda:appointments:write. How to get a token.

Path parameters

appointmentId
string
required
Organization-owned appointment identifier.

pattern: ^eng_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Request body JSON required

expectedVersion
integer
required
Version last read by the caller. The mutation fails if another writer has changed this record.
status
tentative
or
scheduled
or
confirmed
or
checked_in
or
completed
or
cancelled
+2 more
required
Current appointment lifecycle state; cancelled and completed appointments cannot regain capacity through a status change.
reason
optional
string
Why: kept for a cancellation or a no-show, ignored otherwise.

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- bookingChannel
  string | null
  required
  Booking source recorded on the appointment; null when no channel was recorded.
- configurationVersionId
  string | null
  required
  Immutable operating profile version captured when the appointment was booked; null when none applied.
  
  pattern: ^spv_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
- contactId
  string | null
  required
  External contact reference associated with this booking; null when it has no external contact.
  
  pattern: ^cnt_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
- createdAt
  string
  required
  Instant when the scheduling record was first created.
  
  format: date-time
- createdBy
  string | null
  required
  Principal reference of whoever booked it; compare with the session's subject.
  
  default: null
- endsAt
  string
  required
  Exclusive end of the visible appointment or slot, before allocation buffers are added.
  
  format: date-time
- id
  string
  required
  Organization-owned appointment identifier.
  
  pattern: ^eng_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
- intake
  required
  Appointment-specific contact, payer, authorization and custom-field values; null when no intake was recorded.
  
  default: null
  One of the following:
  AgendaAppointmentIntake
  authorization
  string | null
  required
  Payer authorization reference recorded with this appointment; null when absent.
  
  maxLength: 80 · minLength: 1 · default: null
  conversationUrl
  string | null
  required
  HTTPS link to the originating Arbol conversation on an admitted product hostname; null when absent.
  
  format: uri · maxLength: 500 · default: null
  email
  string | null
  required
  Patient email address for enabled appointment notices; null when unknown.
  
  format: email · maxLength: 254 · default: null
  entity
  string | null
  required
  Patient payer or insurer as named by the clinic; null when unknown. It is unrelated to the authenticated organization.
  
  maxLength: 120 · minLength: 1 · default: null
  fields
  object
  required
  Custom patient values keyed by the organization's configured field keys; values retain their declared string, number or boolean type.
  
  default: {}
  notes
  string | null
  required
  Appointment-specific free-text notes; null when none are recorded.
  
  maxLength: 1000 · minLength: 1 · default: null
  phone
  string | null
  required
  Patient contact phone, preserving its entered formatting; null when unknown.
  
  pattern: ^\+?[0-9 ()-]{7,20}$ · default: null
  priority
  normal
  or
  urgent
  required
  Appointment priority: normal by default or urgent when explicitly requested.
  
  default: "normal"
  null
- object
  string
  required
  scheduling.appointment identifies this appointment.
- occupationMinutes
  integer | null
  required
  Study length in minutes the desk chose when booking (6, 8 or 12 hours of a sleep study); its agendas stay held that long from the start. Null: the service’s usual length.
  
  minimum: 1 · default: null
- offeringId
  string | null
  required
  Offering recorded on the appointment; null when the appointment has no linked offering.
  
  pattern: ^off_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
- origin
  native
  or
  provider
  required
  Whether the appointment originated in Scheduling or an imported provider record.
- overbooked
  boolean
  required
  A sobrecupo: the desk added it at a full time or outside hours; it never takes capacity. A move into a free slot makes it a regular appointment.
  
  default: false
- patient
  required
  Patient identity copied into the booking; null when no patient identity was supplied.
  
  default: null
  One of the following:
  AgendaPatientIdentity
  document
  deprecated
  string | null
  required
  Deprecated: use documentNumber. Answered until 2027-01-28.
  
  maxLength: 32 · minLength: 1 · pattern: ^[A-Z0-9]+$
  documentNumber
  string | null
  required
  Normalized patient document number; null when no document is recorded. Identity combines its type and number.
  
  maxLength: 32 · minLength: 1 · pattern: ^[A-Z0-9]+$
  documentType
  string | null
  required
  Organization-configured document type code. A number without a supplied type uses the configured first type; no number means no stored type.
  
  pattern: ^[A-Z][A-Z0-9]{0,9}$ · default: null
  name
  string
  required
  Patient display name with surrounding whitespace removed.
  
  maxLength: 200 · minLength: 1
  null
- patientId
  string | null
  required
  The patient record this booking created or updated; null without a patient.
  
  pattern: ^pat_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ · default: null
- resourceIds
  array of
  string
  required
  Agendas assigned to the appointment or slot, including required professionals, rooms and equipment.
  
  pattern: ^srs_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
- schemaVersion
  number
  required
  Revision of the public record shape; separate from the record version used for concurrency control.
- startsAt
  string
  required
  Visible appointment or slot start instant, including an explicit timezone offset.
  
  format: date-time
- status
  tentative
  or
  scheduled
  or
  confirmed
  or
  checked_in
  or
  completed
  or
  cancelled
  +2 more
  required
  Current appointment lifecycle state; cancelled and completed appointments cannot regain capacity through a status change.
- statusChange
  required
  The latest status change: when, by whom, and the reason given.
  
  default: null
  One of the following:
  AgendaAppointmentStatusChange
  at
  string
  required
  Instant when the appointment change was recorded.
  
  format: date-time
  by
  string | null
  required
  Principal reference of the person who changed the status; null when the actor was not recorded.
  
  reason
  string | null
  required
  Reason recorded for this scheduling change; null when no reason was supplied.
  
  null
- timezone
  string
  required
  IANA timezone used to interpret local dates and agenda working hours.
  
  maxLength: 120 · minLength: 1
- title
  string | null
  required
  Desk-authored appointment title; null permits the service name to supply the display title.
- updatedAt
  string
  required
  Instant of the latest change to this scheduling record.
  
  format: date-time
- version
  integer
  required
  Current record revision; pass it unchanged as expectedVersion for a guarded mutation.
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.
INVALID_APPOINTMENT_INTAKE: Correct the indicated patient or intake fields before booking.
INVALID_PATIENT_FIELDS: Correct the indicated patient fields before saving.
DURATION_CHANGE_OFF: This service does not allow changing appointment duration.
DURATION_NOT_ALLOWED: Select a duration allowed by this service.
STUDY_LENGTH_NOT_OFFERED: Select one of the study lengths this agenda offers.
INVALID_FILE_KIND: Select a supported attachment kind.
INVALID_FILE_NAME: Provide a valid attachment filename.
INVALID_ID_TOKEN: Provide a valid identity token.
INVALID_JSON: Send a valid JSON document.
INVALID_WINDOW: Provide a positive time window within the supported range.
UNEXPECTED_QUERY_PARAMETERS: Remove query parameters not declared by this operation.
INVALID_BODY: The request body could not be read. Send valid uncompressed JSON.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.
ID_TOKEN_MISMATCH: The identity token does not match the authenticated user.
NOT_FILE_UPLOADER: Only the uploader may delete this attachment.
NOT_NOTE_AUTHOR: Only the author may edit or delete this note.
ORIGIN_NOT_ALLOWED: This request origin is not allowed.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested resource does not exist.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

409

PAYER_STAFF_ONLY: This payer requires booking by the organization team. Add the patient to the waitlist for review.
APPOINTMENT_NOT_REMINDABLE: Only an open future appointment with a patient email can receive a reminder.
APPOINTMENT_WITHOUT_PATIENT: Link a patient to this appointment before performing this action.
ARBOL_CATALOG_TOO_LARGE: The integration catalog exceeds the supported size. Narrow the catalog before retrying.
ARBOL_CONFIGURATION_REQUIRED: Configure the organization integration before using it.
NOTIFICATIONS_NOT_SET_UP: Patient emails need the notifications module turned on.
SAME_OFFERING: An agenda cannot take its own appointments.
SAME_SERVICE: A service cannot be merged into itself.
INVALID_HOLD_PAYLOAD: The held slot is malformed.
HOLD_NOT_ACTIVE: The hold is no longer active.
APPOINTMENT_CLOSED: A cancelled appointment cannot be edited.
APPOINTMENT_VERSION_MISMATCH: The appointment changed after it was loaded.
APPOINTMENT_NOT_MOVABLE: A closed appointment cannot be moved.
SERVICE_CHANGED: The new slot belongs to another service.
SCHEDULE_CHANGED: The selected time no longer matches the current schedule.
INVALID_AVAILABILITY_WINDOW: Availability windows must be positive and at most 31 days.
SERVICE_CAPACITY_EXCEEDED: This service already has as many appointments as it can run at once at that time.
RESOURCE_CAPACITY_EXCEEDED: The selected time is no longer available.
OVERBOOK_OUT_OF_RANGE: An overbooked appointment must start between yesterday and the booking horizon.
OVERBOOK_UNAVAILABLE: No active agenda can take this appointment.
STUDY_OVERBOOKING_NOT_ALLOWED: This study has an explicit capacity limit and requires an available ordinary slot.
INVALID_SLOT_TOKEN: Request a fresh available slot before booking.
BIRTH_DATE_REQUIRED: This service has an age rule: the patient's date of birth is required.
AGE_NOT_ELIGIBLE: The patient's age on that day is outside this service's age rule.
INTAKE_SETTINGS_VERSION_MISMATCH: Intake settings changed; reload before saving.
PAYER_NAME_TAKEN: Another payer already has that name.
PAYER_VERSION_MISMATCH: The payer changed; reload before saving.
LOCATION_VERSION_MISMATCH: The site changed after it was loaded.
PROFILE_VERSION_MISMATCH: The profile changed after it was loaded.
PROVIDER_DISABLED: Enable the provider integration before using it.
BINDING_VERSION_MISMATCH: Connection changed or is synchronizing; refresh and retry.
RESOURCE_VERSION_MISMATCH: The resource changed after it was loaded.
SCHEDULE_RULE_AGENDA_MISMATCH: The schedule rule belongs to another agenda.
SCHEDULE_RULE_EXPECTED_VERSION_REQUIRED: Expected version is required for an update.
SCHEDULE_RULE_VERSION_MISMATCH: The schedule rule changed after it was loaded.
SCHEDULE_RULES_CHANGED: The schedule changed after it was loaded.
SERVICE_VERSION_MISMATCH: The service changed after it was loaded.
OFFERING_VERSION_MISMATCH: The offering changed after it was loaded.
SAME_RESOURCE: An agenda cannot take its own appointments.
TARGET_INACTIVE: An archived agenda takes no appointments.
SLOT_REQUIRED: A hold or slot token is required.
ARBOL_SETTINGS_VERSION_MISMATCH: Arbol settings changed.
NOTIFICATION_SETTINGS_VERSION_MISMATCH: Notification settings changed; reload before saving.
ORGANIZATION_VERSION_MISMATCH: The organization changed; reload before saving.
PATIENT_DOCUMENT_TAKEN: Another patient has that document.
PATIENT_VERSION_MISMATCH: The patient changed after it was loaded.
DAILY_REPORT_TOO_LARGE: Daily report exceeds the supported size; no partial report was generated.
REPORT_SETTINGS_VERSION_MISMATCH: Report settings changed; reload before saving.
REPORT_NOTIFICATIONS_DISABLED: Enable the notifications module before sending a daily agenda.
REPORT_RECIPIENTS_REQUIRED: No eligible organization owner or additional delivery address is available for this agenda.
WAITLIST_ENTRY_VERSION_MISMATCH: The waitlist entry changed; reload before saving.
REMOVAL_JOB_CONFLICT: A removal is already active, or this idempotency key belongs to another decision.
FOLLOWUP_SETTINGS_VERSION_MISMATCH: Follow-up email settings changed; reload before saving.
FOLLOWUP_DISABLED: Turn this follow-up email on in the notification settings first.
FOLLOWUP_CONSENT_REQUIRED: The patient has not consented to this follow-up email for their current address.
PATIENT_EMAIL_REQUIRED: Record the patient's email before this action.
PATIENT_ARCHIVED: Restore the patient before this action.
RECALL_ALREADY_ACTIVE: The patient already has an active recall for this service.
RECALL_MONTH_PASSED: The recall's month has already passed.
RECALL_VISIT_REQUIRED: Enter the last visit: there is no attended appointment of this service for the patient.
RECALL_VISIT_IN_FUTURE: The last visit must be a past date.
RECALL_VERSION_MISMATCH: The recall changed after it was loaded.
SLOT_OFFER_NOT_ALLOWED: Only an open waiting-list entry of a registered patient can receive a slot offer.
SLOT_OFFER_MISMATCH: The slot belongs to another service or agenda than the entry asks for.
SLOT_OFFER_TOO_SOON: The slot starts too soon to hold it for the patient; offer a later one.
SLOT_OFFER_ALREADY_OPEN: This waiting-list entry already has an open slot offer.
SLOT_OFFER_CLOSED: The slot offer is no longer open.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.
APPLICATION_JSON_REQUIRED: Send the request as application/json.
FILE_CONTENT_MISMATCH: The uploaded content does not match its declared file type.
UNSUPPORTED_CONTENT_ENCODING: Send an uncompressed request body.
UNSUPPORTED_FILE_TYPE: Select a supported attachment file type.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

426

UPGRADE_REQUIRED: Open the live channel with a WebSocket upgrade.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
ARBOL_RESPONSE_TOO_LARGE: The integration response exceeds the supported size.
ARBOL_UNAVAILABLE: The integration service is temporarily unavailable. Retry later.
REMOVAL_WORKFLOW_UNAVAILABLE: Durable removal is unavailable here; use the bounded manual removal operations.
ARBOL_REFUSED: The integration service rejected this request. Review its configuration.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}