Skip to content
DutiesBook API
Open app

Manage appointments

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.

Change an appointment in your system, then tell DutiesBook: it updates its copy and tells the customer on WhatsApp. {id} is always your appointmentId, as you answered it to the booking.

Every change answers with the appointment as it now is, and whether the customer was told:

200 OK
{
"success": true,
"data": {
"appointment": { "appointmentId": "APT-10293", "status": "confirmed", "…": "…" },
"notification": { "sent": true, "via": "template" }
}
}
notificationMeaning
sent: truevia: message (into the open chat) or template (an approved template, outside the 24-hour window).
sent: falsereason: no_phone, no_channel, template_not_ready, send_failed, or not_requested when you asked not to tell them.
POST /appointments/{id}/accept
POST /appointments/{id}/reject

For a booking you answered pending. The customer gets the acceptance, or the rejection. Reject takes an optional reason (up to 500 characters), kept with the appointment for your team; the customer isn’t shown it. Either answers APT_006 once the booking has been handled, or when its time has passed. Staff can accept it in DutiesBook too; you then get appointment.accepted. Rejecting stays yours.

Accept

curl -X POST \
https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/accept \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"

Reject, with a reason

curl -X POST \
https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/reject \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"reason": "Doctor away"
}'
POST /appointments/{id}/cancel
reason string Optional
Up to 500 characters, kept with the appointment
notifyCustomer boolean Optional
Default true: the customer is told it was cancelled

A cancellation you make isn’t sent back to you as an event; only the customer’s is.

curl -X POST \
https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/cancel \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"reason": "Doctor away",
"notifyCustomer": true
}'
POST /appointments/{id}/reschedule
ModeWhat happens
askThe appointment is cancelled and the customer is asked to choose a new time: inside the 24-hour window, the booking form opens on its reschedule screen; outside it, a template with “Choose a new time”. Their choice arrives as a booking with previousAppointmentId. The booking rules’ cutoff and one-reschedule limit don’t apply to it.
setYou already moved it. DutiesBook moves its copy (same appointmentId) and tells the customer the new time; the reminder counts from it. Leave out providerId to keep the provider; null for none.

When hours change

When a provider’s or a location’s hours change in your system, decide for each appointment it affects: cancel it, ask the customer for a new time, set a new time yourself, or keep it (and call nothing).

Ask the customer for a new time

curl -X POST \
https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/reschedule \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"mode": "ask",
"reason": "Doctor away"
}'

Set the new time yourself

curl -X POST \
https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/reschedule \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"mode": "set",
"date": "2026-11-13",
"time": "14:00",
"providerId": "prv_sara"
}'
PATCH /appointments/{id}

Same time, another provider (null for none). The customer is told who they’ll see, unless notifyCustomer is false.

curl -X PATCH \
https://app.dutiesbook.com/api/external/v1/appointments/APT-10293 \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"providerId": "prv_khaled",
"notifyCustomer": true
}'
GET /appointments/{id}
GET /appointments?from=2026-11-01&to=2026-12-01&status=confirmed&page=1

The appointments as DutiesBook has them, to reconcile with yours. The list is by start time, 100 per page, filtered by from / to (ISO dates or times, on the start) and status, and answers { appointments, page, limit, total }.

FieldDescription
statuspending, confirmed, rejected, cancelled, or rescheduled (the customer moved it; the new time is another appointment).
cancelledByWhen cancelled: customer (from WhatsApp), business (you, including an ask), or reschedule.
start / endThe same time as date and time, in UTC.

One appointment

curl \
https://app.dutiesbook.com/api/external/v1/appointments/APT-10293 \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"

A list

curl \
https://app.dutiesbook.com/api/external/v1/appointments?from=2026-11-01&to=2026-12-01&status=confirmed&page=1 \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
An appointment
{
"appointmentId": "APT-10293",
"status": "confirmed",
"date": "2026-11-12",
"time": "09:30",
"timezone": "Asia/Riyadh",
"start": "2026-11-12T06:30:00.000Z",
"end": "2026-11-12T07:00:00.000Z",
"locationId": "loc_olaya",
"serviceId": "svc_dental",
"subServiceId": "sub_cleaning",
"providerId": "prv_ahmed",
"customer": { "name": "Sara Ali", "phone": "966501234567" },
"bookingRequestId": "br_6730f1c2a9e4b1d2c3e4f5a6",
"requestId": "REQ-7781",
"cancelledBy": null,
"createdAt": "2026-11-11T10:04:01.000Z",
"updatedAt": "2026-11-11T10:04:01.000Z"
}
APT_002 409

No booking system is connected

APT_004 400

A field is missing or invalid, e.g. a time in the past or one the location's clock skips

APT_005 404

No appointment with that ID

APT_006 409

Not pending any more: already accepted or rejected, or its time has passed

APT_007 409

Not active: already cancelled, rejected, or in the past