Search bookable offerings

Search active bookable offerings by q (such as electroencefalograma or neurología), exact serviceId or locationId. Pass the known service name instead of loading the whole catalog. Returns a compact page with offering/service ids, agendas, sites, current bookingChecklist, staff guidance (description), patientInstructions, eligibility (the ages a service takes, in completed years on the appointment day; null for any age) and occupationMinutes (how long the patient stays when longer than the appointment, such as a 12-hour study). Check these requirements against known patient facts before slots or booking; explain patient instructions, and ask only for missing required facts. When eligibility is set, ask the patient's date of birth before booking and pass it as patientBirthDate. If exactly one location applies, use it automatically without asking the patient to choose a site; provide its address for arrival or booking confirmation. Never infer age from a name or document type. A listed service does not establish payer coverage. Follow pageInfo.nextCursor only if needed.

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: response up to 8 MB
CLI: arbol agenda booking-offerings list · MCP tool: agenda_booking_offerings_list

GET

https://api.getarbol.com/v1/agenda/booking-offerings

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.

Query parameters

cursor
optional
string
Opaque cursor returned by pageInfo; omit it to request the first page.
direction
optional
forward
or
backward
Direction to traverse the stable keyset ordering from the supplied cursor.

default: "forward"
limit
optional
integer
Maximum items returned in one page. Defaults to 10; larger reads require another cursor.

maximum: 20 · minimum: 1 · default: 10
locationId
optional
string
Clinic site associated with this record; null means it is not tied to a site.

pattern: ^loc_[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}$
serviceId
optional
string
Service whose bookable offerings or appointments are addressed.

pattern: ^svc_[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}$
q
optional
string
Free-text filter: a service or offering name, or part of one.
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-]+$
query
optional
string
Deprecated: use q. Answered until 2027-01-28.

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- data
  array of
  object
  required
  Items admitted by this resource contract within the verified organization.
  
  agendas
  array of
  object
  required
  Bounded agenda projection for this offering; truncatedAgendas indicates that more agendas exist.
  
  id
  string
  required
  Agenda identifier usable as resourceId when narrowing availability.
  
  kind
  practitioner
  or
  assistant
  or
  room
  or
  chair
  or
  equipment
  or
  location
  +2 more
  required
  Agenda category, such as professional, room or equipment.
  
  locationId
  string | null
  required
  Site owning this agenda; null for an agenda without a site.
  
  name
  string
  required
  Agenda display name for a professional or other schedulable resource.
  
  durationMinutes
  number
  required
  Booked appointment duration in minutes for this offering.
  
  id
  string
  required
  Bookable offering identifier used when requesting signed availability slots.
  
  locations
  array of
  object
  required
  Sites applicable to the offering’s agendas, including addresses for patient arrival.
  
  address
  string | null
  required
  Site street address to tell the patient; null when unset.
  
  city
  string | null
  required
  Site city to tell the patient; null when unset.
  
  id
  string
  required
  Site identifier usable as locationId when narrowing availability.
  
  name
  string
  required
  Site display name for selecting and explaining the appointment location.
  
  timezone
  string
  required
  Site IANA timezone for interpreting appointment and working-hour displays.
  
  name
  string
  required
  Offering display name combining the service and its bookable agenda configuration.
  
  occupationMinutes
  number | null
  required
  Patient occupation in minutes when it differs from the appointment duration; null means no separate duration.
  
  scheduleSummary
  string
  required
  Human-readable service hours and closures. Availability remains authoritative.
  
  scheduleTimezones
  array of
  string
  required
  IANA timezones of the agendas in this bounded projection; hours are interpreted locally.
  
  service
  object
  required
  Current service policy and patient instructions; this projection does not establish payer coverage.
  
  arrivalOrder
  boolean
  required
  Whether this service attends patients by arrival order.
  
  bookingChecklist
  array of
  string
  required
  Staff booking requirements to compare against known patient facts before offering a slot.
  
  description
  string | null
  required
  Staff-facing service guidance for booking; null when not configured.
  
  eligibility
  object | null
  required
  Age eligibility evaluated on the appointment date; null means no configured age restriction.
  
  maxAgeYears
  optional
  integer | null
  Oldest accepted age in completed years; null or absent means no upper age bound.
  
  maximum: 120 · minimum: 0
  minAgeYears
  optional
  integer | null
  Youngest accepted age in completed years; null or absent means no lower age bound.
  
  maximum: 120 · minimum: 0
  id
  string
  required
  Service identifier used for first-available searches and waitlist requests.
  
  name
  string
  required
  Service display name to use when discussing the requested care.
  
  patientInstructions
  string | null
  required
  Preparation and arrival instructions intended for the patient; null when unset.
  
  serviceId
  string
  required
  Service identifier associated with this offering.
  
  truncatedAgendas
  boolean
  required
  Whether the bounded agenda projection omits additional agendas for this offering.
- object
  string
  required
  Discriminator for a resource list response.
- pageInfo
  object
  required
  Opaque navigation cursors for this page’s stable keyset order.
  
  hasNextPage
  boolean
  required
  Whether a later page exists in the current ordering.
  
  hasPreviousPage
  boolean
  required
  Whether an earlier page exists in the current ordering.
  
  nextCursor
  string | null
  required
  Opaque cursor for the next page, or null when there is none.
  
  previousCursor
  string | null
  required
  Opaque cursor for the previous page, or null when there is none.
}
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
}