Manage appointments
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:
{ "success": true, "data": { "appointment": { "appointmentId": "APT-10293", "status": "confirmed", "…": "…" }, "notification": { "sent": true, "via": "template" } }}notification | Meaning |
|---|---|
sent: true | via: message (into the open chat) or template (an approved template, outside the 24-hour window). |
sent: false | reason: no_phone, no_channel, template_not_ready, send_failed, or not_requested when you asked not to tell them. |
Accept or reject
Section titled “Accept or reject”/appointments/{id}/accept /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"// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/accept', { method: 'POST', headers: { 'X-Account-Id': process.env.DUTIES_ACCOUNT_ID, 'X-Api-Key': process.env.DUTIES_API_KEY, 'X-Secret-Key': process.env.DUTIES_SECRET_KEY, },});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/accept", 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"], },)
result = response.json()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" }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/reject', { 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({ "reason": "Doctor away" }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/reject", 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={ "reason": "Doctor away", },)
result = response.json()Cancel
Section titled “Cancel”/appointments/{id}/cancel reason string Optional notifyCustomer boolean Optional true: the customer is told it was cancelledA 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 }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/cancel', { 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({ "reason": "Doctor away", "notifyCustomer": true }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/cancel", 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={ "reason": "Doctor away", "notifyCustomer": True, },)
result = response.json()Reschedule
Section titled “Reschedule”/appointments/{id}/reschedule | Mode | What happens |
|---|---|
ask | The 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. |
set | You 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" }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/reschedule', { 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({ "mode": "ask", "reason": "Doctor away" }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/reschedule", 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={ "mode": "ask", "reason": "Doctor away", },)
result = response.json()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" }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/reschedule', { 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({ "mode": "set", "date": "2026-11-13", "time": "14:00", "providerId": "prv_sara" }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/appointments/APT-10293/reschedule", 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={ "mode": "set", "date": "2026-11-13", "time": "14:00", "providerId": "prv_sara", },)
result = response.json()Change the provider
Section titled “Change the provider”/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 }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/APT-10293', { method: 'PATCH', 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({ "providerId": "prv_khaled", "notifyCustomer": true }),});
const result = await response.json();import osimport requests
response = requests.patch( "https://app.dutiesbook.com/api/external/v1/appointments/APT-10293", 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={ "providerId": "prv_khaled", "notifyCustomer": True, },)
result = response.json()Read appointments
Section titled “Read appointments”/appointments/{id} /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 }.
| Field | Description |
|---|---|
status | pending, confirmed, rejected, cancelled, or rescheduled (the customer moved it; the new time is another appointment). |
cancelledBy | When cancelled: customer (from WhatsApp), business (you, including an ask), or reschedule. |
start / end | The 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"// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/APT-10293', { method: 'GET', headers: { 'X-Account-Id': process.env.DUTIES_ACCOUNT_ID, 'X-Api-Key': process.env.DUTIES_API_KEY, 'X-Secret-Key': process.env.DUTIES_SECRET_KEY, },});
const result = await response.json();import osimport requests
response = requests.get( "https://app.dutiesbook.com/api/external/v1/appointments/APT-10293", 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"], },)
result = response.json()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"// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments?from=2026-11-01&to=2026-12-01&status=confirmed&page=1', { method: 'GET', headers: { 'X-Account-Id': process.env.DUTIES_ACCOUNT_ID, 'X-Api-Key': process.env.DUTIES_API_KEY, 'X-Secret-Key': process.env.DUTIES_SECRET_KEY, },});
const result = await response.json();import osimport requests
response = requests.get( "https://app.dutiesbook.com/api/external/v1/appointments?from=2026-11-01&to=2026-12-01&status=confirmed&page=1", 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"], },)
result = response.json(){ "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"}Errors
Section titled “Errors”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