> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Appointments

> Bookable services in Omneo: definitions, availability, statuses, waitlists, walk-in queues, and booking questionnaires.

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](/concepts/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](/concepts/glossary#d).

* An **Appointment Definition** describes a bookable service: duration, buffers, [booking type](#booking-types), 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](#waitlists-and-walk-in-queues).                                                 |
| `allow_queue`                | Whether the [walk-in queue](#waitlists-and-walk-in-queues) 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:

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

| `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](/concepts/ratings/questionnaires) 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](/dev-guides/visits/appointments) 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](/concepts/automation/targets) 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](/dev-guides/visits/appointments#filtering-appointments-by-type) in the developer guide.

## Related

* [Visits](/concepts/visits)
* [Working with appointments](/dev-guides/visits/appointments)
* [Managing visits](/business-guides/visits/managing-visits)
* [Targets](/concepts/automation/targets)
* [Appointment API](/api-reference/appointment/browse-appointments)
* [Profile Appointment API](/api-reference/profile-appointment/browse-profile-appointments)
* [Appointment Definition API](/api-reference/appointment-definition/browse-appointment-definitions)
* [Appointment Availability API](/api-reference/appointment-availability/browse-available-appointment-slots)
* [Profile Normal Hour API](/api-reference/profile-normal-hour/browse-profile-normal-hours)
* [Profile Special Hour API](/api-reference/profile-special-hour/browse-profile-special-hours)