Booking requests
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.
/appointments/booking-requests Request body
Section titled “Request body”requestId string Required requestId again answers with the first request and sends nothing.customer object Required Show 2 child fields Hide 2 child fields
name string Required phone string Required +966501234567language string Optional en (default) or ar: the form’s and the messages’ languageexpiresInHours number Optional booking_request.expired.Response
Section titled “Response”A requestId already sent answers 200 OK with that request as it is now; its status may be sent, booked, expired or failed.
bookingRequestId 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 }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/booking-requests', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Account-Id': process.env.DUTIES_ACCOUNT_ID, 'X-Api-Key': process.env.DUTIES_API_KEY, 'X-Secret-Key': process.env.DUTIES_SECRET_KEY, }, body: JSON.stringify({ "requestId": "REQ-7781", "customer": { "name": "Sara Ali", "phone": "+966501234567" }, "language": "ar", "expiresInHours": 24 }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/appointments/booking-requests", headers={ "X-Account-Id": os.environ["DUTIES_ACCOUNT_ID"], "X-Api-Key": os.environ["DUTIES_API_KEY"], "X-Secret-Key": os.environ["DUTIES_SECRET_KEY"], }, json={ "requestId": "REQ-7781", "customer": { "name": "Sara Ali", "phone": "+966501234567", }, "language": "ar", "expiresInHours": 24, },)
result = response.json(){ "success": true, "data": { "bookingRequestId": "br_6730f1c2a9e4b1d2c3e4f5a6", "requestId": "REQ-7781", "status": "sent", "via": "template", "expiresAt": "2026-11-12T10:00:00.000Z" }}Errors
Section titled “Errors”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