Skip to content
DutiesBook API
Open app

Appointments overview

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.

Keep your bookings in your own system and let customers book on WhatsApp. DutiesBook sends the customer a booking form and fills its lists from your API while they pick. When they confirm, it sends you the booking to save and tells them what you answered. After that, it keeps you told about everything the customer does.

  1. Appointments is on for your organization. It’s an Enterprise add-on; ask your DutiesBook contact.
  2. Settings › Booking is set to “In your own booking system”. An organization takes bookings one way only: in DutiesBook, or in your system. Until an admin chooses yours, the API answers APT_010.
  3. The WhatsApp setup on that page is finished. It makes the booking form and the message templates on your appointments number, in Arabic and English.
  4. You have an API key with the Appointments permission. If the key is limited to some channels, the appointments number must be one of them; otherwise every call answers AUTH_008.
  5. Your webhook URL is set in Settings › Booking. DutiesBook sends every booking and every event to that one URL. Until an admin sets it, nothing can be booked: booking requests answer APT_011.
  1. You connect once. DutiesBook checks your GET /auth/verify and gives you a signing secret.
  2. You send a customer the booking form.
  3. The customer opens the form on WhatsApp. Each screen asks your API for its list: locations, services, providers, dates, times.
  4. The customer taps Confirm. DutiesBook posts the booking to your webhook URL and waits for your answer: 201 books it, 409 sends the customer back to pick another time.
  5. DutiesBook sends the customer their confirmation, then the reminders and the Cancel and Reschedule buttons.
  6. You manage the appointment (accept, reject, cancel, move), and DutiesBook tells you what the customer, and your team in DutiesBook, does.

Base URL https://app.dutiesbook.com/api/external/v1, with the usual authentication headers.

MethodEndpointDescription
POST/appointments/connectionConnect, or reconnect, your booking system
DELETE/appointments/connectionDisconnect it
POST/appointments/booking-requestsSend a customer the booking form
GET/appointmentsYour appointments, as DutiesBook has them
GET/appointments/{id}One appointment
POST/appointments/{id}/acceptAccept a pending booking
POST/appointments/{id}/rejectReject a pending booking
POST/appointments/{id}/cancelCancel an appointment
POST/appointments/{id}/rescheduleAsk the customer for a new time, or move it
PATCH/appointments/{id}Another provider, same time

The lists on the baseUrl you connect with; bookings and events on the webhook URL set in Settings › Booking. All with Authorization: Bearer <your token>.

MethodEndpointDescription
GET/auth/verifyChecks the connection
GET/locationsThe form’s locations
GET/servicesServices and sub-services at a location
GET/providersProviders for a location and sub-service
GET/datesDays with a free time
GET/timesFree times on a day
POST{webhookUrl}Every booking (live) and every event
TopicRule
IDsLocations, services, providers and appointments use your IDs: any string. DutiesBook passes them back to you unchanged.
LanguageEvery list request carries language (en or ar). Return names in that language.
Dates and timesYYYY-MM-DD and HH:mm (24-hour), always in the location’s own timezone.
TimeoutsLists answer within 2.5 s (WhatsApp gives a screen 10 s in all). The booking answers within 5 s, because the customer is waiting.
MessagesDutiesBook sends the customer every message: confirmations, reminders (unless you send them: see reminders on connect), and the changes you make.

DutiesBook keeps a copy

Every booking you accept is kept in DutiesBook too, so your team sees it in the inbox and on the Appointments page, and the customer’s buttons keep working.

Staff can book, move, cancel and accept your appointments from DutiesBook too. Your system stays in charge of the free times and the catalog: staff pick from your lists and never edit your locations, services or providers.

Staff doWhat you get
Book, or send the booking formThe booking, with bookedBy: "staff" (or "customer" for the form). Nothing is kept until you answer.
Move to a time they pickThe booking for the new time, with previousAppointmentId.
Ask the customer to choose a new timeappointment.cancelled with rescheduleRequested: true, then the customer’s booking naming it.
Cancelappointment.cancelled with cancelledBy: "staff" and their reason.
Accept a pending bookingappointment.accepted.

Rejecting a pending booking stays in your system.