Skip to content
DutiesBook API
Open app

Endpoints you build

Enterprise

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.

Authorization: Bearer <the token you connected with>
User-Agent: DutiesBook-Appointments/1

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.

GET {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).

GET {baseUrl}/locations?language=ar
{
"locations": [
{ "id": "loc_olaya", "name": "الرياض – العليا", "timezone": "Asia/Riyadh", "address": "طريق العليا، الرياض" }
]
}
id string Required
Your ID
name string Required
In the requested language
timezone string Required
IANA, e.g. Asia/Riyadh. Dates and times at this location are read in it.
address string Optional
Shown under the name
GET {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
Minutes, 1–1440. Shown to the customer, and sets the appointment’s end.
subServices[].price number Optional
Shown with currency
subServices[].currency string With price
ISO 4217, e.g. SAR
GET {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.

GET {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.

GET {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.

POST {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
}
FieldDescription
bookingRequestIdThe same one can arrive twice (a doubled tap, a retry after a timeout): answer with the same appointmentId, and never book twice.
previousAppointmentIdSet 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.
providerIdnull when the customer picked “Any provider”.
requestIdYour requestId, or null for a booking DutiesBook started: staff booking, a form staff sent, or the customer’s “Book a new appointment”.
bookedBycustomer: they picked on the WhatsApp form. staff: someone on your team picked it in DutiesBook.
notesWhat staff wrote when they booked, or null.
201 Created
{ "appointmentId": "APT-10293", "status": "confirmed" }
appointmentId string Required
Your ID. Every later call names the appointment by it.
status string Optional
confirmed (default), or pending if your team reviews it first: then accept or reject it.
providerId string Optional
Who you assigned, when the customer picked "Any provider"
Your answerWhat the customer sees
2xx with appointmentIdThe booking is made; they get the confirmation on WhatsApp (“request received” when pending).
409They 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.