Appointments - Omneo API

An Appointment in Omneo is a booking made against an Appointment Definition. It records who is booked, where, when, the current status, the assigned staff member where one is required, and any answers captured by the booking questionnaire. Appointments power scheduled services such as consultations, fittings, repairs, and events.

Appointments and visits

Appointments and Visits both describe a customer at a physical location, but they answer different questions.

Object	Answers	When to use
Visit	Was the customer here?	Capture attendance or footfall, with or without a booking.
Appointment	What did the customer book, and what happened to that booking?	Scheduling, availability, staff assignment, approval, waitlists, and queues.

An appointment can sit alongside a visit: the appointment is the booking, the visit is the record of attendance.

Definitions and appointments

Appointments follow the Definition/Instance pattern.

An Appointment Definition describes a bookable service: duration, buffers, booking type, opening hours, the locations and staff it is offered at, capacity, an optional booking questionnaire, and notification settings. It is the template and the schedule.
An Appointment is a single booking against a definition.

Most flows start with the customer choosing a definition, then drive into availability, booking, and status updates.

Booking types

The booking_type on a definition sets how customers book.

`booking_type`	Behaviour	Notes
`instant`	The appointment is confirmed the moment it is booked.	`confirmed_at` is set immediately.
`approval_required`	The customer creates a request; staff confirm or reject it.	Starts as `requested`. `confirmed_at` or `rejected_at` is set on the status change.
`walk_in_only`	No advance booking. Customers join a walk-in queue at the location.	Requires `allow_walk_in: true` and `allow_customer_booking: false`. Availability returns no slots.

Independent flags layer on top of the booking type:

Flag	Meaning
`allow_customer_booking`	Whether customers can self-book.
`allow_walk_in`	Whether walk-in queue check-in is allowed.
`requires_staff`	Whether a booking has a specific assigned staff member.
`customer_must_select_staff`	When `requires_staff` is true, forces the customer to choose. Cannot be true unless `requires_staff` is true.
`max_concurrent_bookings`	Capacity per slot for non-staff definitions. For staff-required definitions, capacity is one per staff member per slot.
`allow_waitlist`	Whether customers can join a waitlist.
`allow_queue`	Whether the walk-in queue is available.

Status lifecycle

An appointment moves through a set of statuses, each with a matching timestamp that Omneo sets automatically on the change.

requested -> confirmed -> arrived -> completed
                       -> cancelled
                       -> rejected
                       -> no_show

Status	Set when	Timestamp
`requested`	A booking needs approval, or as the default on create.	`created_at`
`confirmed`	The booking is accepted (immediately for `instant`).	`confirmed_at`
`arrived`	The customer checks in.	`arrived_at`
`completed`	The service is finished.	`completed_at`
`cancelled`	The booking is cancelled.	`cancelled_at`, plus `cancelled_by`
`rejected`	An approval request is declined.	`rejected_at`, plus `rejected_by`
`no_show`	The customer did not attend.	`no_show_at`

Availability

Availability is the set of bookable slots Omneo calculates for a definition at a location on a date. Omneo derives slots by intersecting:

The definition’s opening hours for that day.
The location’s opening hours.
The assigned staff member’s hours, when the definition requires staff.
Existing bookings, which subtract from capacity.
The definition’s min_lead_minutes and max_advance_days, which cap the bookable window.

Definitions carry normal hours (a weekly pattern, one entry per day) and special hours (dated overrides such as public holidays or one-off changes). Special hours take precedence over normal hours when a date matches. For non-staff definitions, each slot reports capacity_remaining, derived from max_concurrent_bookings minus the bookings already in that slot. For staff-required definitions, capacity is implicitly one per staff member per slot.

Where staff come from

When a definition requires staff, the eligible staff pool depends on use_staff_from_location.

`use_staff_from_location`	Staff source	Location check
`true` (default)	Staff assigned to the location, minus anyone whose profile excludes this definition’s service `handle`.	Staff must be active at the requested location for the date.
`false`	An explicit allow-list of staff attached to the definition.	Not checked. The staff member travels to the location; their own hours still gate availability.

Waitlists and walk-in queues

Two related flows handle demand that a normal booking cannot.

A Waitlist lets a customer register interest when no suitable slot is available. When a slot opens, an operator fulfils the entry by creating an appointment and linking it, or the customer cancels. Waitlist entries move through active, then fulfilled or cancelled. Enabled with allow_waitlist.
A Queue is the walk-in queue for a definition that allows walk-ins. A customer, named or anonymous, checks in at a location and moves through waiting, called, then served or cancelled. A served entry can be converted into an appointment. Enabled with allow_queue.

Booking questionnaires

A definition can carry a booking Questionnaire: a versioned form built from reusable Questions. Customers answer it as part of booking, and the answers are stored with the appointment. Questionnaires are pinned by version: an appointment keeps the form version that was active when it was booked, so editing the form later never rewrites historical answers. Each answer can be routed to a destination such as a profile field, a transaction, or a rating. Questionnaires are not limited to appointments. The same Question and Questionnaire model is used for standalone surveys such as NPS, CSAT, and profile updates, and each answer can be routed to a profile field, a rating, or a transaction. See the appointments developer guide for how booking answers are submitted.

Notifications

A definition can schedule notifications for each lifecycle event (created, confirmed, cancelled, rejected, and reminders) by pointing at a Target and setting an offset. Rescheduling an appointment re-schedules its pending reminders. The notifications are configured on the definition, not triggered per booking.

Time and timezone handling

Appointment times are written in a request timezone (an IANA name such as Australia/Melbourne) and stored in UTC. Every datetime field on the appointment is returned in UTC. Convert to local time on the client using the timezone on the appointment or on its nested location. Definition opening hours are plain times, local to the location’s timezone.

Appointment types

There is no separate category or type field on an Appointment Definition. The definition itself is the type: an “Event” definition and a “Service” definition are two different definitions, and every appointment booked against one is of that type. To work with appointments by type, filter the appointments list by definition id (filter[appointment_definition_id]). See filtering appointments by type in the developer guide.

​Appointments and visits

​Definitions and appointments

​Booking types

​Status lifecycle

​Availability

​Where staff come from

​Waitlists and walk-in queues

​Booking questionnaires

​Notifications

​Time and timezone handling

​Appointment types

​Related