Skip to content
HeyX API

List Appointments

Required scope: appointment:read

Lists appointments overlapping a required time window. fromUnix and toUnix are Unix seconds and must be positive with toUnix after fromUnix; the window may not exceed 400 days. Narrow results with the optional agendaId, memberId, customerId, and status filters.

Results are capped at pageSize (up to 100; the cap applies when pageSize is 0 or omitted). hasMore reports whether the window held more appointments than the returned page. Reading another member’s schedule requires broad calendar visibility; without it, filtering by that member is denied.

Generated Reference
POST /public-api/publicapi.v1.Appointment/ListAppointments

Lists appointments whose scheduled start falls inside a required time window, with optional agenda, member, customer and status filters. Results are capped at page_size; has_more reports whether the window held more.

Request ListAppointmentsRequest
Response ListAppointmentsResponse

ListAppointmentsRequest

Field Type Description
from_unix int64 Inclusive lower bound (unix seconds) on scheduled start. Required so every query is bounded to a finite window.
to_unix int64 Exclusive upper bound (unix seconds) on scheduled start. Must be greater than from_unix; the window may not exceed 400 days.
agenda_id optional string Restrict to one agenda.
member_id optional string Restrict to one assigned member; another member's schedule requires scheduling read access.
customer_id optional string Restrict to one customer.
status optional AppointmentStatus Restrict to one status.
page_size int32 Maximum appointments to return, 1-100; zero uses 100. When more matched, has_more is set and the window or filters should be narrowed.

ListAppointmentsResponse

Field Type Description
appointments repeated Appointment Appointments in the requested window, capped at page_size.
has_more bool True when the window contained more appointments than were returned.

Related Types

Appointment

Field Type Description
id string Appointment identifier.
customer_id string Customer the appointment is booked for.
agenda_id string Agenda the appointment belongs to.
appointment_type_id string Appointment type applied to the appointment.
assigned_member_id string Member currently assigned, or empty when unassigned.
scheduled_start_at int64 Scheduled start as unix seconds.
scheduled_end_at int64 Scheduled end as unix seconds.
duration_minutes int32 Scheduled duration in minutes.
status AppointmentStatus Current lifecycle status.
notes string Free-text notes stored on the appointment.
created_at int64 Unix seconds when the appointment was created.
updated_at int64 Unix seconds when the appointment was last updated. 
{
  "fromUnix": "1788220800",
  "toUnix": "1788307200",
  "agendaId": "<agenda-id>",
  "status": "PUBLIC_APPOINTMENT_STATUS_SCHEDULED",
  "pageSize": 100
}
HeyX API