Skip to main content
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. An appointment can sit alongside a visit: the appointment is the booking, and the visit, an interaction, 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. Definitions also carry content fields (short_description, long_description, icon, image_url, terms_conditions) that front-end booking flows can display, and an internal_notes field for operator use.
  • 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. Independent flags layer on top of the booking type:

​
Status lifecycle

An appointment has a status, and Omneo stamps the matching timestamp automatically whenever the status changes. The typical progression is:
Omneo does not enforce a fixed order. You can set any status directly and Omneo records its timestamp, so a requested booking can be cancelled or marked no_show without being confirmed first. Appointments booked against instant or walk_in_only definitions are confirmed automatically on creation, so confirmed_at is set straight away. Creating an appointment with an explicit status of confirmed also sets confirmed_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:
  1. The definition’s opening hours for that day.
  2. The location’s opening hours.
  3. The assigned staff member’s hours, when the definition requires staff.
  4. Existing bookings, which subtract from capacity.
  5. 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. The same normal and special hour pattern applies at the profile level: a staff member who is also a Profile can have their own normal and special hours, which gate their individual availability for staff-required definitions. 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.

​
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. An appointment can reference other records:
  • Transaction or Order: attach a completed Transaction or a pending Order, for example to tie a consultation to the sale that followed. Each is a single association, set when creating or updating the appointment and cleared by setting it to null.
  • Profiles and Lists: link one or more Profiles or Lists to an appointment, separate from the profile the appointment is booked for. This uses the dedicated link and unlink endpoints, and linking the same record twice is idempotent.

​
Notifications

A definition can schedule notifications for each lifecycle event (created, confirmed, completed, 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.

​
Visibility conditions

A definition can carry a visibility_condition: a JsonLogic rule evaluated against the Profile requesting the list. When the rule evaluates to true for a given Profile, that definition is included in the response from the profile-scoped visibility endpoint (GET /v3/profiles/{profile}/appointment-definitions/visibility). The endpoint only returns published, non-archived definitions. A null visibility_condition means the definition never passes the check. To make a definition visible to all qualifying profiles, set an explicit condition that always returns true (for example {"==": [1, 1]}). Visibility conditions are evaluated server-side using the Profile’s attributes as context. They follow the same JsonLogic approach used elsewhere in Omneo (such as Reactions).

​
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.