Use case: Booking an appointment via the API

Using the Public API, you can trigger an appointment booking entirely from your own system – for example from your own website, an app, or a kiosk terminal. This requires five API calls that build on each other: you first query the bookable services, determine the appropriate staff members, reserve a time slot, attach customer data, and finalize the booking.

Select Query services and staff members (Steps 1–2).

Reserve Temporarily block time slot (Step 3).

Finalize Attach customer data and book (Steps 4–5).

All five interfaces are part of the Public API and require no API key. In the examples, replace <YourBusiness> with your own calendar name. You can find an overview of all interfaces in the API Reference.

The process in five steps

1
Query services
You send the ID of your location (servicerGroupId) and receive all bookable services in return – grouped (groups) and individually (services) with name, duration, and price. Optionally, filter narrows down the selection.
Save the id of each desired service.
Request POST https://<YourBusiness>.belbo.com/externalBooking/calcGroups servicerGroupId=16
2
Find matching staff members
With the list of service IDs (selectedProducts, comma-separated), you query which staff members can perform these services. The response provides under groupToServicers the available staff members for each position with name and ID – if the ratings module is active, also the average rating.
Save the id of the desired staff member – or -1 for "any".
Request POST https://<YourBusiness>.belbo.com/externalBooking/calcServicers servicerGroupId=16&selectedProducts=180612
3
Start booking – Reserve time slot
This call expects a JSON body with date, time, the selected services, and the staff member. It does not book yet, but reserves the time slot. You receive back the two keys you need for the remaining steps: appointmentId and appointmentParticipantId. If the appointment has been taken in the meantime, the interface responds with "result": "GIVEN".
Request (JSON body, abbreviated) POST https://<YourBusiness>.belbo.com/newAppointment/bookAppointmentAPI { "date": "15.07.2026", "time": "13:00", "selectedProducts": [180612], "servicerGroupId": 16, "bookingGroups": { "0": -1 }, "bookingSource": "Your API" }
4
Add customer data
You now attach the customer data to the reserved booking: first name, last name, title, mobile number, and email address. The fields privacy, terms, and webBooking confirm privacy policy and terms – obtain this consent in your own interface before sending yes here.
Request POST https://<YourBusiness>.belbo.com/externalBooking/persistCustomerData appointmentId=…&firstName=Petra&name=Smith&genderType=FEMALE &mobile=0123456789&email=petra@example.com&privacy=yes&terms=yes
5
Finalize booking
Only this call turns the reservation into a confirmed appointment. With "result": "OK", the booking is visible in the calendar, and Belbo sends confirmation emails to the customer and business.
Request POST https://<YourBusiness>.belbo.com/externalBooking/finalizeBooking appointmentId=…&appointmentParticipantId=…

What you should pay attention to

Where does the time come from?

Step 3 requires date and time. Which times are available at all is provided by the Available Appointments interface – with the same information about location, services, and staff member.

Carry two keys with you

Everything after step 3 depends on appointmentId and appointmentParticipantId. Keep both in your session until completion.

Reservation is not a booking

If you break off between step 3 and 5, only an incomplete reservation remains – the appointment is not booked and no email is sent.

All fields in detail You can find parameters, example responses, and additional interfaces in the API Reference.

To the API Reference