Endpoints you build
Appointments is available on Enterprise plans only, added on request. Until it's on for your
organization, every Appointments endpoint answers 403 APT_001.
The booking form has no lists of its own: each screen asks your API for its list as the customer reaches it. When they confirm, DutiesBook sends you the booking and waits for your answer. Every call carries your token.
Answer fast
WhatsApp gives a form screen 10 seconds in all, so each list must answer within 2.5 seconds; a slower or failed list shows the customer an empty list. Lists may be a bare array or wrapped in an object, as below. Unusable items (no id or name, a bad timezone) are left out rather than failing the list.
Verify
Section titled “Verify”{baseUrl}/auth/verify Called when you connect and when staff click “Check connection”. Any 2xx is a working connection. Optionally answer with your system’s name: { "ok": true, "name": "Al Amal Clinics" }.
“Check connection” in Settings › Booking then calls every endpoint on this page in order, the way a customer’s form would: the locations, the services at the first one, the providers and free days for its first sub-service, and the times on the first free day. Last it sends a signed ping to your webhook URL. Staff see each endpoint’s result: answered, how many items, how long it took, or why it failed (an HTTP error, no answer, an unexpected answer, or no locations or services).
Locations
Section titled “Locations”{baseUrl}/locations?language=ar { "locations": [ { "id": "loc_olaya", "name": "الرياض – العليا", "timezone": "Asia/Riyadh", "address": "طريق العليا، الرياض" } ]}id string Required name string Required timezone string Required Asia/Riyadh. Dates and times at this location are read in it.address string Optional Services
Section titled “Services”{baseUrl}/services?locationId=loc_olaya&language=ar The services offered at the location, each with its sub-services. A sub-service is what’s booked.
{ "services": [ { "id": "svc_dental", "name": "الأسنان", "subServices": [ { "id": "sub_cleaning", "name": "تنظيف", "duration": 30, "price": 150, "currency": "SAR" } ] } ]}subServices[].duration number Required subServices[].price number Optional currencysubServices[].currency string With price SARProviders
Section titled “Providers”{baseUrl}/providers?locationId=loc_olaya&subServiceId=sub_cleaning&language=ar { "providers": [ { "id": "prv_ahmed", "name": "د. أحمد" } ] }The form always offers “Any provider” first. When the customer picks it, the next calls carry no providerId. Return an empty list if you don’t book by provider: “Any provider” is then the only choice.
{baseUrl}/dates?locationId=loc_olaya&subServiceId=sub_cleaning&providerId=prv_ahmed&language=ar { "dates": ["2026-11-12", "2026-11-14", "2026-11-15"] }The days with at least one free time. Every other day shows greyed out.
{baseUrl}/times?locationId=loc_olaya&subServiceId=sub_cleaning&providerId=prv_ahmed&date=2026-11-12&language=ar { "times": ["09:00", "09:30", "11:00"] }Start times, HH:mm, at the location. The day and time lists are asked again when the customer picks one, so a time taken meanwhile is caught before they confirm.
The booking
Section titled “The booking”{webhookUrl} Sent to your webhook URL (set in Settings › Booking) when the customer taps Confirm, and when staff book or move one of your appointments in DutiesBook. Someone is waiting on your answer: answer within 5 seconds. The body is signed like every event; see Verifying the signature.
One URL for bookings and events
The booking and every event arrive at the same URL. Tell them apart by X-Dutiesbook-Event (or event in the body): appointment.book needs the answer below; an event needs any 2xx.
{ "id": "9b2e4c1a-…", "event": "appointment.book", "occurredAt": "2026-11-11T10:04:00.000Z", "bookingRequestId": "br_6730f1c2a9e4b1d2c3e4f5a6", "requestId": "REQ-7781", "previousAppointmentId": null, "locationId": "loc_olaya", "serviceId": "svc_dental", "subServiceId": "sub_cleaning", "providerId": "prv_ahmed", "date": "2026-11-12", "time": "09:30", "timezone": "Asia/Riyadh", "duration": 30, "customer": { "name": "Sara Ali", "phone": "966501234567" }, "language": "ar", "bookedBy": "customer", "notes": null}| Field | Description |
|---|---|
bookingRequestId | The same one can arrive twice (a doubled tap, a retry after a timeout): answer with the same appointmentId, and never book twice. |
previousAppointmentId | Set when the customer is moving one of your appointments: book the new time and cancel that one, in one go. You may answer with the same appointmentId or a new one. |
providerId | null when the customer picked “Any provider”. |
requestId | Your requestId, or null for a booking DutiesBook started: staff booking, a form staff sent, or the customer’s “Book a new appointment”. |
bookedBy | customer: they picked on the WhatsApp form. staff: someone on your team picked it in DutiesBook. |
notes | What staff wrote when they booked, or null. |
{ "appointmentId": "APT-10293", "status": "confirmed" }appointmentId string Required status string Optional providerId string Optional | Your answer | What the customer sees |
|---|---|
2xx with appointmentId | The booking is made; they get the confirmation on WhatsApp (“request received” when pending). |
409 | They go back to the time list: “This time was just taken”. |
| Anything else, or no answer in 5 s | ”This can’t be booked right now”. Nothing is booked. |
The customer's own rules
Before asking you to move an appointment, DutiesBook applies the organization’s booking rules: the customer reschedules once from WhatsApp, and only until the cutoff before the start. A move you asked for (ask), or one staff made in DutiesBook, is exempt from both.