Skip to content
DutiesBook API
Open app

Booking requests

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.

Every booking you start begins here. You ask DutiesBook to send a customer the booking form; the customer gets a WhatsApp message with a “Book” button that opens it. Their booking comes to your webhook URL, set in Settings › Booking.

POST /appointments/booking-requests
requestId string Required
Your own ID for this request, up to 200 characters. Sending the same requestId again answers with the first request and sends nothing.
customer object Required
Who the form goes to.
Show 2 child fields Hide 2 child fields
name string Required
Up to 150 characters
phone string Required
Their WhatsApp number with its country code, e.g. +966501234567
language string Optional
en (default) or ar: the form’s and the messages’ language
expiresInHours number Optional
1–168, default 24. A form not booked by then expires, and you get booking_request.expired.

A requestId already sent answers 200 OK with that request as it is now; its status may be sent, booked, expired or failed.

bookingRequestId
DutiesBook's ID for the request. The booking carries it; deduplicate the booking on it.
via
message: sent into the customer's open chat (they wrote in the last 24 hours). template: sent as the approved booking template, which works at any time.
status
sent, then booked, expired, or failed (WhatsApp couldn't deliver it; failure says why).

When the form isn't booked

If WhatsApp reports the message undeliverable, you get booking_request.failed; if the customer doesn’t book before expiresAt, booking_request.expired. Both go to your webhook URL. See Events.

curl -X POST \
https://app.dutiesbook.com/api/external/v1/appointments/booking-requests \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"requestId": "REQ-7781",
"customer": {
"name": "Sara Ali",
"phone": "+966501234567"
},
"language": "ar",
"expiresInHours": 24
}'
202 Accepted
{
"success": true,
"data": {
"bookingRequestId": "br_6730f1c2a9e4b1d2c3e4f5a6",
"requestId": "REQ-7781",
"status": "sent",
"via": "template",
"expiresAt": "2026-11-12T10:00:00.000Z"
}
}

A form that couldn’t be sent leaves no request behind, so the same requestId can be sent again once it’s fixed.

APT_002 409

No booking system is connected

APT_004 400

A field is missing or invalid (e.g. a phone number without its country code)

APT_008 409

The WhatsApp booking form isn't ready: finish the WhatsApp setup in Settings › Booking

APT_009 422

WhatsApp didn't accept the message, or the contact is over the plan's limit

APT_011 409

No webhook URL is set, so the booking would have nowhere to go: an admin sets it in Settings › Booking