Connection
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.
Connect
Section titled “Connect”/appointments/connection baseUrl string Required https://api.clinic.example/dutiesbook. DutiesBook calls {baseUrl}/auth/verify, {baseUrl}/locations and so on.token string Required 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 }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/connection', { 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({ "baseUrl": "https://api.clinic.example/dutiesbook", "token": "your-bearer-token", "reminders": true }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/appointments/connection", 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={ "baseUrl": "https://api.clinic.example/dutiesbook", "token": "your-bearer-token", "reminders": True, },)
result = response.json(){ "success": true, "data": { "status": "connected", "signingSecret": "whsec_4f1c…", "verifiedAt": "2026-11-11T10:00:00.000Z", "name": "Al Amal Clinics" }}Disconnect
Section titled “Disconnect”/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"// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/appointments/connection', { method: 'DELETE', 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.delete( "https://app.dutiesbook.com/api/external/v1/appointments/connection", 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(){ "success": true, "data": { "status": "revoked" } }Errors
Section titled “Errors”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