Look up a patient's appointments

Find a patient by their exact documentNumber (and documentType, such as CC or TI, when known) and list their appointments, newest first, each with id, start, status and agendas; upcoming ones also carry guidance (patientInstructions, arrivalOrder, who attends and the site's address). Use it before cancelling or rescheduling; found=false means no patient has that document. When several patients share the number under different types, patients lists them and appointments is empty: ask which one and call again with documentType.

Scopes: any one of agenda:bookings:read, agenda:bookings:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: request body up to 256 KB, response up to 8 MB
CLI: arbol agenda bookings lookup · MCP tool: agenda_bookings_lookup

POST

https://api.getarbol.com/v1/agenda/bookings/lookup

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopes agenda:bookings:read, agenda:bookings:write. Get an API key.

Request body JSON required

documentNumber
optional
string
Exact patient document number; normalized for matching, with documentType needed when multiple types share the number.
documentType
optional
string
Document-type code from the organization’s configured active types. Input is trimmed and uppercased.
channel
optional
voice
or
whatsapp
or
web
The conversation's channel, set by the platform. It changes nothing in Agenda; omit it.
connectionId
optional
string
The platform's id for the organization's Agenda, set by the platform. An organization has one Agenda, so it selects nothing; omit it.

maxLength: 128 · minLength: 1 · pattern: ^[\w-]+$
document
deprecated
string
Deprecated: use documentNumber. Answered until 2027-01-28.

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- appointments
  array of
  object
  required
  Appointments for the uniquely identified patient, newest first; empty when the document is absent or ambiguous.
  
  endsAt
  string
  required
  Appointment end as an ISO instant.
  
  guidance
  required
  Current arrival guidance for upcoming appointments; null for past appointments or absent projection.
  
  One of the following:
  AgendaAppointmentGuidance
  arrivalOrder
  boolean
  required
  Whether patients are attended in arrival order rather than by the exact booked minute.
  
  attendedBy
  array of
  string
  required
  Names of the professionals currently assigned to the appointment.
  
  location
  object | null
  required
  Current site for the appointment, including arrival address; null when no site applies.
  
  address
  string | null
  required
  Current site street address; null when not configured.
  
  city
  string | null
  required
  Current site city; null when not configured.
  
  name
  string
  required
  Current site name to tell the patient before arrival.
  
  patientInstructions
  string | null
  required
  Current service preparation and arrival instructions to relay to the patient; null when unset.
  
  serviceName
  string | null
  required
  Current booked service name; null when no service projection is available.
  
  null
  id
  string
  required
  Appointment identifier used to read, cancel or reschedule the selected booking.
  
  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}$
  resourceIds
  array of
  string
  required
  Agenda identifiers allocated to this appointment.
  
  startsAt
  string
  required
  Appointment start as an ISO instant.
  
  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.
  
  version
  number
  required
  Current appointment version used by guarded cancellation and rescheduling.
- found
  boolean
  required
  Whether an exact document match exists; a true value may still require document-type disambiguation.
- patient
  optional
  object
  Current patient record and appointment summary within the verified organization.
  
  addressLine
  string | null
  required
  Patient street address as recorded by staff; null when unknown.
  
  alert
  string | null
  required
  Staff-visible patient care warning; null when none is recorded.
  
  archivedAt
  string | null
  required
  ISO instant when the record was archived; null while active. Archived records remain readable by id.
  
  birthDate
  string | null
  required
  Patient date of birth as YYYY-MM-DD; null when unknown.
  
  city
  string | null
  required
  Patient municipality as written by staff, not a geographic code; null when unknown.
  
  createdAt
  string
  required
  ISO instant when the patient record was created.
  
  document
  deprecated
  string | null
  required
  Deprecated: use documentNumber. Answered until 2027-01-28.
  
  documentNumber
  string | null
  required
  Normalized patient document number; null when no document is recorded. Identity combines its type and number.
  
  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.
  
  email
  string | null
  required
  Patient email address for enabled appointment notices; null when unknown.
  
  entity
  string | null
  required
  Patient payer or insurer as named by the clinic; null when unknown. It is unrelated to the authenticated organization.
  
  fields
  object
  required
  Custom patient values keyed by the organization's configured field keys; values retain their declared string, number or boolean type.
  
  gender
  male
  or
  female
  or
  other
  or
  unknown
  or
  null
  required
  FHIR administrative gender recorded for registration; null when unknown.
  
  id
  string
  required
  Identifier of this patient record within the verified organization.
  
  name
  string
  required
  Patient display name with surrounding whitespace removed.
  
  object
  string
  required
  Discriminator identifying the scheduling.patient response shape.
  
  phone
  string | null
  required
  Patient contact phone, preserving its entered formatting; null when unknown.
  
  updatedAt
  string
  required
  ISO instant of the latest patient record change.
  
  version
  number
  required
  Current patient record version; send it as expectedVersion for a compare-and-set edit.
  
  cancelled
  number
  required
  Number of this patient's nondeleted appointments currently cancelled.
  
  lastAt
  string | null
  required
  Latest past appointment start as an ISO instant, excluding cancelled appointments; null when none exists.
  
  nextAt
  string | null
  required
  Earliest upcoming open appointment start as an ISO instant; null when none exists.
  
  noShow
  number
  required
  Number of this patient's nondeleted appointments currently marked as no-show.
  
  total
  number
  required
  Number of this patient's nondeleted appointments across all statuses.
- patients
  optional
  array of
  object
  Candidate patients when an exact document number matches multiple document types; omitted after unique identification.
  
  document
  deprecated
  string | null
  required
  Deprecated: use documentNumber. Answered until 2027-01-28.
  
  documentNumber
  string | null
  required
  Matched patient’s normalized document number; null when absent from the record.
  
  documentType
  string | null
  required
  Matched patient’s organization document-type code; use it to resolve a shared document number.
  
  id
  string
  required
  Patient record identifier belonging to the verified organization.
  
  name
  string
  required
  Patient display name for asking which matching document type applies.
}
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
}