Skip to content

Booking ​

The Booking extension accepts client bookings from your website. Every booking becomes a task of the form, and occupied time is checked on the server: two clients cannot book the same time with the same master.

What to prepare ​

FormWhat it holds
Bookings (the form with the extension)A Date field with the period turned on, client fields (Text, Phone, Email), links to the master and the services
Services (optional)Name, duration in minutes (Number), price (Number), optionally a category and a break after the service
Masters (optional)Name, schedule (Schedule field), optionally a user (Person) and a table of the master's services

Without a services form a booking has a fixed length. Without a masters form the form has one shared calendar.

Setup ​

  1. Bot. A user with the BOT role that has access to the form with the right to create tasks. Bookings from the site are created on its behalf.
  2. Date field. A Date field with a period: it receives the start and end of the booking.
  3. Timezone and allowed sites — the addresses the widget may call the API from, one per line.
  4. Services and Masters. Pick the forms that hold services and masters. The settings get service and resource blocks, and the fields of the picked forms are listed below with their ids.
  5. Fill in the field ids in the JSON instead of null: at least duration_field_id, the duration field of the services form.
  6. Save and turn the extension on.

The AI admin can set booking up too: tell it which form should take online bookings.

Services: one or several ​

The mode follows from how the bookings form links to the services form. Use one of the two.

ModeIn the bookings formBlock in the settings
One service per bookingA Form field linked to the services form"service": {"field_id": ...}
Several services in a row with one masterA Table with a Form column linked to the services form"service": {"table": {...}, "max_services": 5}

With several services the booking length is the sum of the durations, the break is taken from the last service, and the price field receives the total.

json
"service": {
  "table": {
    "table_field_id": 6090,
    "service_column_id": 6091,
    "price_column_id": 6092,
    "duration_column_id": 6093
  },
  "max_services": 5,
  "duration_field_id": 6070,
  "price_field_id": 6071,
  "category_field_id": 6072,
  "buffer_field_id": null
}

duration_field_id, price_field_id, category_field_id and buffer_field_id are fields of the services form. The other ids are fields of the bookings form.

Masters ​

json
"resource": {
  "field_id": 6079,
  "schedule_field_id": 6060,
  "person_field_id": null,
  "services_table": {
    "table_field_id": 6061,
    "service_column_id": 6062,
    "price_column_id": null,
    "duration_column_id": null
  }
}
SettingMeaning
field_idField of the bookings form linked to the masters form
schedule_field_idSchedule field in the master's card: the master's working hours
person_field_idPerson field in the master's card: the user's working hours and absences apply
services_tableTable in the master's card: which services the master does

Working hours of a master are taken in this order: schedule in the card → the user's schedule → resource.working_hours → the shared working_hours. Days of the user's absence are closed entirely.

Services of a master. With services_table set, a master is offered only for the services in their table. A master with an empty table is not offered for any service.

Own price and duration. The price_column_id and duration_column_id columns are needed only when masters have their own prices or times. A filled cell replaces the value from the services form and does not follow its later changes; an empty one means "as in the services form".

Other settings ​

SettingMeaning
slot_step_minGrid of start times, minutes
min_lead_minHow many minutes before the start a booking is still accepted
max_days_aheadHow many days ahead the calendar is open
working_hoursShared working hours: {"mon": [["09:00","13:00"],["14:00","18:00"]], "sun": []}
default_duration_minBooking length when there are no services
price_field_idNumber field of the bookings form that receives the price
client_fieldsWhat the site may send: [{"key": "name", "form_field_id": 6081, "required": true}]. Field types: Text, Textarea, Phone, Email

Booking widget on a website ​

The API address and the key are shown on the Website connection tab. The key is public: it can be written in the page code. The site must be in the allowed list.

Answers come as {"success": true|false, "error_message": ..., "data": ...}.

1. Catalog — once on page load ​

GET {base}
FieldMeaning
servicesServices: id, name, duration_min, price, category
resourcesMasters: id, name, service_ids — the services the master does
max_servicesHow many services one booking may hold; 1 means one
fieldsClient fields: key, label, type, required
timezone, slot_step_min, max_days_aheadTimezone and calendar limits

2. Masters for the chosen services ​

Filter the list in the widget itself, without a request: show a master only if their service_ids include every chosen service. A master without service_ids does any service.

A separate request is needed only when masters have their own prices or durations:

GET {base}/resources?service_ids=12,15

Each master in the answer has service with their own price and duration.

3. Free time ​

GET {base}/slots?date=2026-11-25&service_ids=12,15&resource_id=51350&include_busy=true
  • Without resource_id it means "any master": a time is free if at least one master who does all the chosen services is free.
  • include_busy=true returns the whole grid with an available flag; without it only free times.
  • Show start as is: it is already in the business timezone.

4. Booking ​

POST {base}/bookings
Content-Type: application/json
Idempotency-Key: <UUID>

{
  "start": "2026-11-25T10:00+02:00",
  "service_ids": ["12", "15"],
  "resource_id": 51350,
  "language": "en",
  "fields": {"name": "Anna", "phone": "+37255512345"}
}

For one service "service_id": "12" works too. Without resource_id the system picks the master. reference in the answer is the booking number.

Rules ​

  • The server checks everything itself. A time outside the schedule, a taken time or a master who does not do the service returns an error, even if the widget let it through.
  • One Idempotency-Key per booking attempt. Reuse the same key when retrying the same request: the booking is not duplicated.
  • 409 with code slot_taken: the time was just taken, load the times again.
  • 400: show error_message to the client. 429: too many requests, try again later.
  • Always ask the server for free time; do not compute it in the widget.

Changing a booking in the system ​

A booking is an ordinary task. When staff change the time or the master, cancel or delete the task, the occupied time follows. A booking created by staff by hand occupies time too and blocks it for the site.