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
| Form | What 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
- Bot. A user with the
BOTrole that has access to the form with the right to create tasks. Bookings from the site are created on its behalf. - Date field. A Date field with a period: it receives the start and end of the booking.
- Timezone and allowed sites — the addresses the widget may call the API from, one per line.
- Services and Masters. Pick the forms that hold services and masters. The settings get
serviceandresourceblocks, and the fields of the picked forms are listed below with their ids. - Fill in the field ids in the JSON instead of
null: at leastduration_field_id, the duration field of the services form. - 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.
| Mode | In the bookings form | Block in the settings |
|---|---|---|
| One service per booking | A Form field linked to the services form | "service": {"field_id": ...} |
| Several services in a row with one master | A 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.
"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
"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
}
}| Setting | Meaning |
|---|---|
field_id | Field of the bookings form linked to the masters form |
schedule_field_id | Schedule field in the master's card: the master's working hours |
person_field_id | Person field in the master's card: the user's working hours and absences apply |
services_table | Table 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
| Setting | Meaning |
|---|---|
slot_step_min | Grid of start times, minutes |
min_lead_min | How many minutes before the start a booking is still accepted |
max_days_ahead | How many days ahead the calendar is open |
working_hours | Shared working hours: {"mon": [["09:00","13:00"],["14:00","18:00"]], "sun": []} |
default_duration_min | Booking length when there are no services |
price_field_id | Number field of the bookings form that receives the price |
client_fields | What 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}| Field | Meaning |
|---|---|
services | Services: id, name, duration_min, price, category |
resources | Masters: id, name, service_ids — the services the master does |
max_services | How many services one booking may hold; 1 means one |
fields | Client fields: key, label, type, required |
timezone, slot_step_min, max_days_ahead | Timezone 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,15Each 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_idit means "any master": a time is free if at least one master who does all the chosen services is free. include_busy=truereturns the whole grid with anavailableflag; without it only free times.- Show
startas 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-Keyper booking attempt. Reuse the same key when retrying the same request: the booking is not duplicated. 409with codeslot_taken: the time was just taken, load the times again.400: showerror_messageto 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.