Skip to content
HeyX API

Create Appointment

Required scope: appointment:create

This endpoint supports active round-robin and choose-user agendas. Agenda, appointment-type, member, and available-slot IDs are configured and discovered in HeyX. For choose-user agendas, assigneeMemberId is required. Omitting it on a round-robin agenda lets HeyX select an eligible member.

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

Creates a direct appointment on a round-robin or choose-user agenda. This operation is not idempotent and must not be blindly retried.

Request CreateAppointmentRequest
Response CreateAppointmentResponse

CreateAppointmentRequest

Field Type Description
customer_id string Customer the appointment is booked for.
agenda_id string Agenda that governs availability, routing and slot rules.
appointment_type_id string Appointment type that sets the default and allowed durations.
scheduled_start_at int64 Start time as unix seconds.
duration_minutes int32 Zero uses the appointment type default.
notes string Free-text notes stored on the appointment.
assignee_member_id optional string Required by choose-user agendas; optional for round-robin agendas.

CreateAppointmentResponse

Field Type Description
appointment Appointment The created appointment.

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. 
{
  "customerId": "<customer-id>",
  "agendaId": "<agenda-id>",
  "appointmentTypeId": "<appointment-type-id>",
  "scheduledStartAt": "1788260400",
  "durationMinutes": 60,
  "notes": "Customer confirmed access",
  "assigneeMemberId": "<member-id>"
}

This operation is not idempotent. Check slot availability and do not blindly retry after a timeout.

HeyX API