Skip to content
DutiesBook API
Open app

Connection

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.

Your system connects itself, once: it tells DutiesBook where its API is and the token to call it with. Connect again at any time to change either. The connection shows in DutiesBook under Settings › Booking, where staff can check it or end it.

POST /appointments/connection
baseUrl string Required
Your API, HTTPS on a public address, e.g. https://api.clinic.example/dutiesbook. DutiesBook calls {baseUrl}/auth/verify, {baseUrl}/locations and so on.
token string Required
Sent as Authorization: Bearer <token> on every call to your API. 8–2048 characters.
reminders boolean Optional
true (default): DutiesBook sends the customer a reminder before each appointment, by its booking rules. false: you send them.

Before keeping anything, DutiesBook calls your GET {baseUrl}/auth/verify with the token. Any 2xx answer connects; anything else answers APT_003 and nothing is saved.

Keep the signing secret

Use signingSecret to verify everything DutiesBook posts to you: the booking and every event. See Verifying the signature. Connecting again keeps the same secret.

name is what your /auth/verify answered as { "name": "…" }, if anything. Staff see it on the settings page.

Where DutiesBook sends you bookings and events

Not part of the connection: an admin sets your webhook URL in Settings › Booking. Every booking and every event goes there, to the URL as it is when each is sent. Until it’s set, nothing can be booked.

curl -X POST \
https://app.dutiesbook.com/api/external/v1/appointments/connection \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"baseUrl": "https://api.clinic.example/dutiesbook",
"token": "your-bearer-token",
"reminders": true
}'
200 OK
{
"success": true,
"data": {
"status": "connected",
"signingSecret": "whsec_4f1c…",
"verifiedAt": "2026-11-11T10:00:00.000Z",
"name": "Al Amal Clinics"
}
}
DELETE /appointments/connection

DutiesBook stops calling your API at once. A customer who opens a booking form sent before then can’t book. Appointments already booked stay, and their customers still get their messages.

Disconnecting again changes nothing. When staff disconnect from the settings page, you get connection.revoked on your webhook URL. Switching the organization back to taking bookings in DutiesBook disconnects you the same way.

curl -X DELETE \
https://app.dutiesbook.com/api/external/v1/appointments/connection \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
200 OK
{ "success": true, "data": { "status": "revoked" } }
APT_001 403

Appointments is not turned on for this organization. It is available on Enterprise plans only, added on request.

APT_003 422

Your GET {baseUrl}/auth/verify did not answer 2xx with the token given

APT_004 400

A field is missing or invalid, e.g. a URL that isn't HTTPS

APT_010 409

The organization takes bookings in DutiesBook: an admin must choose 'In your own booking system' in Settings › Booking

AUTH_008 403

The key is limited to some channels, and the appointments WhatsApp number isn't one of them