Managing appointment definitions

An Appointment Definition is the bookable service behind every appointment: it sets the duration, booking type, opening hours, the locations and staff it is offered at, capacity, an optional booking questionnaire, notifications, and visibility rules. Create one before customers can book. For the model behind definitions, see the Appointments concept. All endpoints are bearer authenticated and live under https://api.[tenant].getomneo.com/api/v3.

Create a definition

Send a POST to /appointment-definitions. Only handle, name, duration_minutes, and booking_type are required. Everything else has a default or can be added later.

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-definitions" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "bra-fitting",
    "name": "Bra fitting",
    "short_description": "A 30 minute fitting with a specialist.",
    "duration_minutes": 30,
    "booking_type": "approval_required",
    "buffer_before_minutes": 5,
    "buffer_after_minutes": 5,
    "min_lead_minutes": 120,
    "max_advance_days": 30,
    "slot_interval_minutes": 15,
    "allow_customer_booking": true,
    "requires_staff": true,
    "customer_must_select_staff": false,
    "use_staff_from_location": true,
    "max_concurrent_bookings": null,
    "allow_waitlist": true,
    "allow_queue": false,
    "location_ids": [13, 14],
    "is_published": false,
    "is_archived": false
  }'

The response is 201 with the saved definition, including its generated id. Use that id on the nested endpoints below and as appointment_definition_id when creating appointments.

Field reference

Field	Type	Notes
`handle`	string	Required. Unique handle for the definition. Use this, not a slug or key.
`name`	string	Required. Display name shown in booking flows.
`duration_minutes`	integer	Required. Length of one booking.
`booking_type`	enum	Required. `instant`, `approval_required`, or `walk_in_only`. See below.
`description`, `short_description`, `long_description`	string	Copy for the booking flow.
`icon`, `image_url`	string	Display assets for the booking flow.
`terms_conditions`	string	Terms shown to the customer at booking.
`internal_notes`	string	Operator-only note. Not customer facing.
`buffer_before_minutes`, `buffer_after_minutes`	integer	Padding held before and after each booking.
`min_lead_minutes`	integer	Minimum notice before a slot can be booked.
`max_advance_days`	integer	How far ahead a slot can be booked.
`slot_interval_minutes`	integer	Spacing between slot start times.
`meta`	object	Custom key/value data.

min_lead_minutes, max_advance_days, the buffers, and the opening hours together define which slots the availability endpoints return.

Booking type and capability flags

booking_type sets how customers book against the definition.

`booking_type`	Behaviour
`instant`	The appointment is confirmed the moment it is booked.
`approval_required`	The customer creates a request; an operator confirms or rejects it.
`walk_in_only`	No advance booking. Customers join a walk-in queue at the location.

Independent capability flags layer on top of the booking type.

Flag	Type	Notes
`allow_customer_booking`	boolean	Whether customers can self-book.
`allow_walk_in`	boolean	Whether walk-in check-in is allowed.
`requires_staff`	boolean	Whether each booking has an assigned staff member.
`customer_must_select_staff`	boolean	Forces the customer to choose a staff member. Set `requires_staff` to `true` as well.
`use_staff_from_location`	boolean	Where the eligible staff pool comes from. See Locations and staff.
`max_concurrent_bookings`	integer or null	Capacity per slot for non-staff definitions. `null` means unlimited. For staff-required definitions, capacity is one per staff member per slot.
`allow_waitlist`	boolean	Whether customers can join a waitlist.
`allow_queue`	boolean	Whether the walk-in queue is available.

Set max_concurrent_bookings to null for group services with no fixed cap, such as a class or an event. Leave it unset or null unless the service has a real per-slot limit.

Opening hours

A definition carries two sets of hours, both scoped to the definition itself.

Normal hours are the weekly pattern, one entry per day_of_week.
Special hours are dated overrides such as public holidays or a one-off change. A special hour takes precedence over the normal hour when a date matches.

Create either inline on the definition or through the nested endpoints. Inline is convenient at create time; the nested endpoints let you add, update, or remove single entries later without rewriting the whole definition. Inline on create:

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-definitions" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "bra-fitting",
    "name": "Bra fitting",
    "duration_minutes": 30,
    "booking_type": "approval_required",
    "normal_hours": [
      { "day_of_week": "MON", "available_from": "09:00", "available_until": "17:00" },
      { "day_of_week": "TUE", "available_from": "09:00", "available_until": "17:00" }
    ],
    "special_hours": [
      {
        "name": "Public holiday",
        "is_repeating": false,
        "available_from": "10:00",
        "available_until": "14:00",
        "start_at": "2026-12-25",
        "end_at": "2026-12-25"
      }
    ]
  }'

Add a single normal-hours entry later:

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-definitions/{definitionId}/normal-hours" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "day_of_week": "WED", "available_from": "09:00", "available_until": "13:00" }'

Endpoint	Purpose
`POST /appointment-definitions/{definitionId}/normal-hours`	Add one weekly entry (`day_of_week`, `available_from`, `available_until`).
`POST /appointment-definitions/{definitionId}/special-hours`	Add one dated override (`name`, `start_at`, `end_at`, `available_from`, `available_until`, `is_repeating`).

day_of_week accepts MON, TUE, WED, THU, FRI, SAT, or SUN. Times such as available_from are plain local times at the location. Each nested collection also supports GET, and each entry supports PUT and DELETE at .../normal-hours/{id} and .../special-hours/{id}.

Locations and staff

A definition is offered at one or more locations and, when it requires staff, draws from a staff pool. Attach both on create with location_ids and staff_ids:

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-definitions" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "styling-session",
    "name": "Styling session",
    "duration_minutes": 45,
    "booking_type": "instant",
    "requires_staff": true,
    "use_staff_from_location": false,
    "location_ids": [13, 14],
    "staff_ids": ["a1b460b2-953f-4587-b4eb-fb0f29b55e02"]
  }'

Manage them individually through the nested endpoints:

Endpoint	Purpose
`POST /appointment-definitions/{definitionId}/locations`	Offer the definition at a location.
`POST /appointment-definitions/{definitionId}/staff`	Attach a staff member (`staff_id`, optional `is_active`).

Both collections support GET, and each attachment supports PUT and DELETE at .../locations/{id} and .../staff/{id}. Where staff come from depends on use_staff_from_location:

`use_staff_from_location`	Staff source
`true`	Staff assigned to the requested location.
`false`	The explicit staff attached to the definition through `staff_ids` or the `.../staff` endpoint.

When use_staff_from_location is true, you do not attach staff to the definition. Availability draws from the location’s staff for the requested date. When it is false, attach the staff explicitly; their own hours still gate availability.

Booking questionnaire

To capture answers at booking, attach a booking questionnaire. Send a booking_questionnaire object on the definition, either inline as a new questionnaire or by referencing an existing questionnaire’s questions.

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-definitions" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "bra-fitting",
    "name": "Bra fitting",
    "duration_minutes": 30,
    "booking_type": "approval_required",
    "booking_questionnaire": {
      "name": "Fitting intake",
      "handle": "fitting-intake",
      "is_active": true,
      "questions": [
        {
          "question_handle": "reason-for-visit",
          "mapping_key": "reason",
          "sort_order": 1,
          "is_required": true
        }
      ]
    }
  }'

Each question needs a mapping_key, which routes the answer to a destination. Reference a reusable Question by question_id, question_handle, or a specific question_version_id. Group questions into pages when the form needs sections. Omneo pins the questionnaire by version, so a booked appointment keeps the form version that was active when it was booked. For how questions and questionnaires are built and how answers are routed, see Building questionnaires and the Questionnaires concept.

Notification targets

A definition can send a notification for each lifecycle event by pointing at a Target and setting an offset. Each event has a target field and a matching pair of offset fields in days and hours.

Event	Target field	Offset fields
Created	`created_target_id`	`notify_created_offset_days`, `notify_created_offset_hours`
Confirmed	`confirmed_target_id`	`notify_confirmed_offset_days`, `notify_confirmed_offset_hours`
Completed	`completed_target_id`	`notify_completed_offset_days`, `notify_completed_offset_hours`
Cancelled	`cancelled_target_id`	`notify_cancelled_offset_days`, `notify_cancelled_offset_hours`
Rejected	`rejected_target_id`	`notify_rejected_offset_days`, `notify_rejected_offset_hours`
Reminder	`reminder_target_id`	`notify_reminder_offset_days`, `notify_reminder_offset_hours`

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-definitions/{definitionId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmed_target_id": 42,
    "reminder_target_id": 43,
    "notify_reminder_offset_days": 1,
    "notify_reminder_offset_hours": 0
  }'

The offset positions the notification relative to the appointment’s scheduled start. A reminder offset of one day sends the reminder 24 hours before the booking. Rescheduling an appointment re-schedules its pending reminders.

Visibility conditions

To control which definitions a Profile sees in a customer-facing booking flow, set a visibility_condition: a JsonLogic rule evaluated against the requesting Profile’s attributes.

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-definitions/{definitionId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "visibility_condition": { "==": [1, 1] } }'

Read the definitions a Profile can see from the profile-scoped visibility endpoint:

GET /api/v3/profiles/{profileId}/appointment-definitions/visibility

This returns only published, non-archived definitions whose visibility_condition evaluates to true for that Profile. A null visibility_condition never passes the check, so a definition with null is excluded from the visibility endpoint. To make a definition visible to every qualifying Profile, use a rule that always returns true, such as {"==": [1, 1]}. See Visibility conditions in the concept for how the rule is evaluated.

Publishing a definition

Two flags control whether a definition is live.

Flag	Effect
`is_published`	When `true`, the definition is available to booking flows. Create definitions with `is_published: false` while configuring, then publish.
`is_archived`	When `true`, the definition is retired and excluded from booking flows.

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-definitions/{definitionId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "is_published": true }'

Customer-facing lists filter on both, so query filter[is_published]=1&filter[is_archived]=0 to fetch only live definitions.

The definition resource

A GET /appointment-definitions/{definitionId} returns the full definition wrapped in a data object: every configured field, a has_booking_questionnaire flag, and the loaded normal_hours, special_hours, locations, staff, and booking_questionnaire relations.

{
  "data": {
    "id": 1,
    "handle": "bra-fitting",
    "name": "Bra fitting",
    "description": null,
    "short_description": "A 30 minute fitting with a specialist.",
    "long_description": null,
    "icon": null,
    "image_url": null,
    "terms_conditions": null,
    "internal_notes": null,
    "visibility_condition": { "==": [1, 1] },
    "is_published": true,
    "is_archived": false,
    "duration_minutes": 30,
    "buffer_before_minutes": 5,
    "buffer_after_minutes": 5,
    "min_lead_minutes": 120,
    "max_advance_days": 30,
    "slot_interval_minutes": 15,
    "booking_type": "approval_required",
    "allow_customer_booking": true,
    "allow_walk_in": false,
    "requires_staff": true,
    "customer_must_select_staff": false,
    "use_staff_from_location": true,
    "max_concurrent_bookings": null,
    "allow_waitlist": true,
    "allow_queue": false,
    "meta": {},
    "created_target_id": null,
    "confirmed_target_id": 42,
    "cancelled_target_id": null,
    "rejected_target_id": null,
    "reminder_target_id": 43,
    "completed_target_id": null,
    "notify_created_offset_days": null,
    "notify_created_offset_hours": null,
    "notify_confirmed_offset_days": 0,
    "notify_confirmed_offset_hours": 0,
    "notify_cancelled_offset_days": null,
    "notify_cancelled_offset_hours": null,
    "notify_rejected_offset_days": null,
    "notify_rejected_offset_hours": null,
    "notify_reminder_offset_days": 1,
    "notify_reminder_offset_hours": 0,
    "notify_completed_offset_days": null,
    "notify_completed_offset_hours": null,
    "has_booking_questionnaire": true,
    "normal_hours": [
      { "id": 301, "day_of_week": "MON", "available_from": "09:00", "available_until": "17:00" },
      { "id": 302, "day_of_week": "TUE", "available_from": "09:00", "available_until": "17:00" }
    ],
    "special_hours": [
      {
        "id": 88,
        "name": "Public holiday",
        "is_repeating": false,
        "available_from": "10:00",
        "available_until": "14:00",
        "start_at": "2026-12-25",
        "end_at": "2026-12-25"
      }
    ],
    "locations": [
      { "id": 500, "location_id": 13, "is_active": true },
      { "id": 501, "location_id": 14, "is_active": true }
    ],
    "staff": [
      { "id": 700, "staff_id": "c3d582d4-b75f-47a9-d6fd-1d2b41d77e24", "is_active": true }
    ],
    "booking_questionnaire": {
      "name": "Fitting intake",
      "handle": "fitting-intake",
      "is_active": true,
      "questions": [
        {
          "question_handle": "reason-for-visit",
          "mapping_key": "reason",
          "sort_order": 1,
          "is_required": true
        }
      ]
    },
    "created_at": "2026-05-01T04:00:00Z",
    "updated_at": "2026-05-01T04:00:00Z"
  }
}

Every scalar field you set on create is echoed back: the copy fields, the scheduling fields, booking_type, the capability flags, the notification targets and offsets, visibility_condition, is_published, is_archived, and meta, plus created_at and updated_at in UTC. The relations below are loaded on the read.

Field	Type	Notes
`has_booking_questionnaire`	boolean	Whether a booking questionnaire is attached. A quick check without inspecting `booking_questionnaire`.
`normal_hours`	array	The weekly opening-hours entries, each `{ id, day_of_week, available_from, available_until }`.
`special_hours`	array	The dated overrides, each `{ id, name, is_repeating, available_from, available_until, start_at, end_at }`.
`locations`	array	The definition-location attachments, each `{ id, location_id, is_active }`.
`staff`	array	The attached staff, each `{ id, staff_id, is_active }`. Populated when the definition uses an explicit staff list.
`booking_questionnaire`	object or null	The attached questionnaire with its `questions`, `null` when the definition has none.

End-to-end example: build and publish a definition

Build a definition in a draft state, configure it through the nested endpoints, then publish it once it is complete.

Create a draft

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-definitions" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "bra-fitting",
    "name": "Bra fitting",
    "duration_minutes": 30,
    "booking_type": "approval_required",
    "requires_staff": true,
    "use_staff_from_location": true,
    "location_ids": [13, 14],
    "is_published": false
  }'

The response is 201 with the generated id. Configure everything else while is_published is false.

Add opening hours

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-definitions/1/normal-hours" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "day_of_week": "MON", "available_from": "09:00", "available_until": "17:00" }'

Repeat for each open day, and add special-hours for holidays.

Attach the booking questionnaire and notifications

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-definitions/1" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmed_target_id": 42,
    "reminder_target_id": 43,
    "notify_reminder_offset_days": 1
  }'

Attach the booking questionnaire inline or by reference as shown under Booking questionnaire.

Publish

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-definitions/1" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "is_published": true }'

Read the definition back to confirm its normal_hours, locations, staff, and booking_questionnaire are all in place before customers can book.

Errors

Status	When
`401`	Missing or invalid bearer token.
`403`	The token lacks the required scope, or the actor lacks permission.
`404`	The definition does not exist, or a nested hours, location, or staff entry does not belong to the definition in the URL.
`422`	Validation failed. Create requires `handle`, `name`, `duration_minutes`, and `booking_type`; a missing or invalid one returns `422`.

Edge cases and gotchas

max_concurrent_bookings: null means unlimited. Leave it null for group services with no per-slot cap. Set an integer only when a slot has a real limit. It has no effect on staff-required definitions, where capacity is one per staff member per slot.
customer_must_select_staff needs requires_staff. The customer can only be forced to pick a staff member on a definition that assigns staff, so set requires_staff: true as well.
Opening hours are plain local times. available_from and available_until are local to the location’s timezone and carry no timezone themselves, unlike appointment datetimes, which are stored in UTC.
Special hours win. When a date matches both a normal-hours day and a special-hours entry, the special hour takes precedence for that date.
Booking questionnaires are pinned by version. A booked appointment keeps the questionnaire version that was active at booking, so editing the form later never rewrites historical answers.
A null visibility_condition is excluded. Such a definition never passes the profile-scoped visibility check. Use {"==": [1, 1]} to make it visible to every qualifying Profile.

​Create a definition

​Field reference

​Booking type and capability flags

​Opening hours

​Locations and staff

​Booking questionnaire

​Notification targets

​Visibility conditions

​Publishing a definition

​The definition resource

​End-to-end example: build and publish a definition

​Errors

​Edge cases and gotchas

​Related

Create a definition

Field reference

Booking type and capability flags

Opening hours

Locations and staff

Booking questionnaire

Notification targets

Visibility conditions

Publishing a definition

The definition resource

End-to-end example: build and publish a definition

Errors

Edge cases and gotchas

Related