Daybook · Developer API
Book appointments from your own software.
Read your services, free times, appointments and customers; book and cancel with a key; and be told the moment anything changes — signed, so you know it came from us.
Use an AI app such as Claude or ChatGPT? Connect an AI agent — it reads your calendar and books for you, with the same rules and the same charges as your screens.
Authentication and conventions
Make a key on your organisation's API & webhooks screen (it is shown once) and send it on every request:
Authorization: Bearer daybook_…
- • Base URL
https://www.drivebird.com/api/daybook/v1. JSON in, JSON out. - • Success:
{"data": …}, plusmetaon lists. Failure:{"data": null, "errors": ["…"], "code": "MACHINE-CODE"}— branch oncode. - • Anything that is not your organisation's, or does not exist, answers 410 Gone. DriveBird never answers 404.
- • Times are ISO 8601 instants in UTC, like
2026-09-14T05:30:00+00:00; every appointment also carries its owntimezone. Money is in minor units (paise for INR), with itscurrency.
Key permissions
A key is READ or READ-WRITE, chosen when you make it. Each endpoint below shows what it needs.
| Permission | What it allows |
|---|---|
READ |
Read only — services, free times, appointments and customers |
READ-WRITE |
Read and write — also books and cancels appointments |
- • A call the key may not make answers 403
KEY-SCOPE-MISSING: the key is fine, so make one with the permission you need. - • Revoke a key on the same screen. From then on it answers 401
UNAUTHENTICATED. - • While your organisation is suspended or closed, every call answers 403
ORGANISATION-CLOSED.
Limits
- • 120 requests per minute for your organisation, and at most 300 per minute from one IP address. Beyond either, a call answers 429
RATE-LIMITED. - • Free times cover at most 14 days a call; list pages hold at most 100 rows.
Endpoints
/api/daybook/v1/services
Needs READ
— Your services, with their lengths, prices and who offers them
Every service you offer that is not archived, hidden ones included, because the key is your own.
curl
curl https://www.drivebird.com/api/daybook/v1/services -H "Authorization: Bearer daybook_…"
PHP (Laravel Http)
$services = Http::withToken($key)->get('https://www.drivebird.com/api/daybook/v1/services')->json('data');
Response
{"data":[{"id":12,"name":"Check-up","slug":"check-up","visibility":"PUBLIC","booking_mode":"INSTANT","meeting_mode":"IN-PERSON","capacity":1,"currency":"INR","durations":[{"id":31,"label":null,"minutes":30,"price_minor":50000,"deposit_minor":0}],"members":[{"id":4,"name":"Asha Rao"}]}]}
/api/daybook/v1/services/{id}/free-times?from=&days=&member_id=&duration_id=
Needs READ
— The free times of a service
from is a date in your organisation's timezone (default today); days is 1–14 (default 7). Without member_id, every member who offers the service is asked. These are the times your booking page offers; post one back exactly as given.
curl
curl "https://www.drivebird.com/api/daybook/v1/services/12/free-times?from=2026-09-14&days=7" -H "Authorization: Bearer daybook_…"
PHP (Laravel Http)
$times = Http::withToken($key)->get('https://www.drivebird.com/api/daybook/v1/services/12/free-times', ['from' => '2026-09-14', 'days' => 7])->json('data');
Response
{"data":[{"starts_at":"2026-09-14T03:30:00+00:00","ends_at":"2026-09-14T04:00:00+00:00","member_id":4,"places_left":null}],"meta":{"service_id":12,"duration_id":31,"from":"2026-09-14","days":7}}
/api/daybook/v1/appointments
Needs READ-WRITE
— Book a free time for a customer
Answers 201. Fields: service_id, member_id and starts_at (from the free times); duration_id (optional — the service's first length); the customer's name (first and last); email and phone (optional). The time is checked again as it is booked: 409 SLOT-TAKEN means it went in the meantime. The customer is sent the usual confirmation, the appointment's history names your key, and the booking is billed like any other confirmed booking.
curl
curl https://www.drivebird.com/api/daybook/v1/appointments -H "Authorization: Bearer daybook_…" -H "Content-Type: application/json" \
-d '{"service_id": 12, "member_id": 4, "starts_at": "2026-09-14T05:30:00+00:00", "name": "Priya Sharma", "email": "priya@example.com"}'
PHP (Laravel Http)
$appointment = Http::withToken($key)->post('https://www.drivebird.com/api/daybook/v1/appointments', [
'service_id' => 12,
'member_id' => 4,
'starts_at' => '2026-09-14T05:30:00+00:00',
'name' => 'Priya Sharma',
'email' => 'priya@example.com',
])->json('data');
Response
{"data":{"id":501,"state":"CONFIRMED","confirmation_mark":"NOT-ASKED","source":"API","service":{"id":12,"name":"Check-up"},"member":{"id":4,"name":"Asha Rao"},"starts_at":"2026-09-14T05:30:00+00:00","ends_at":"2026-09-14T06:00:00+00:00","timezone":"Asia/Kolkata","price_minor":50000,"deposit_minor":0,"currency":"INR","meeting_mode":"IN-PERSON","meeting_url":null,"capacity":1,"booked_count":1,"people":[{"participation_id":1201,"person_id":77,"name":"Priya Sharma","email":"priya@example.com","phone":null,"role":"BOOKER","left_at":null}],"cancelled_at":null,"cancelled_by":null,"cancel_reason":null,"cancel_final_at":null,"rebooked_from_id":null,"series_id":null,"created_at":"2026-09-11T03:30:00+00:00"}}
/api/daybook/v1/appointments?from=&to=&state=&page=&per_page=
Needs READ
— Your appointments in a date range, earliest first
from and to are dates in your timezone, both included (default: today and the next 30 days). state narrows to one state. per_page is 1–100 (default 25).
curl
curl "https://www.drivebird.com/api/daybook/v1/appointments?from=2026-09-14&to=2026-09-20" -H "Authorization: Bearer daybook_…"
PHP (Laravel Http)
$page = Http::withToken($key)->get('https://www.drivebird.com/api/daybook/v1/appointments', ['from' => '2026-09-14', 'to' => '2026-09-20'])->json();
Response
{"data": [ …appointment… ], "meta": {"page": 1, "per_page": 25, "total": 1, "last_page": 1}}
/api/daybook/v1/appointments/{id}
Needs READ
— One appointment
curl
curl https://www.drivebird.com/api/daybook/v1/appointments/501 -H "Authorization: Bearer daybook_…"
PHP (Laravel Http)
$appointment = Http::withToken($key)->get('https://www.drivebird.com/api/daybook/v1/appointments/501')->json('data');
Response
{"data":{"id":501,"state":"CONFIRMED","confirmation_mark":"NOT-ASKED","source":"API","service":{"id":12,"name":"Check-up"},"member":{"id":4,"name":"Asha Rao"},"starts_at":"2026-09-14T05:30:00+00:00","ends_at":"2026-09-14T06:00:00+00:00","timezone":"Asia/Kolkata","price_minor":50000,"deposit_minor":0,"currency":"INR","meeting_mode":"IN-PERSON","meeting_url":null,"capacity":1,"booked_count":1,"people":[{"participation_id":1201,"person_id":77,"name":"Priya Sharma","email":"priya@example.com","phone":null,"role":"BOOKER","left_at":null}],"cancelled_at":null,"cancelled_by":null,"cancel_reason":null,"cancel_final_at":null,"rebooked_from_id":null,"series_id":null,"created_at":"2026-09-11T03:30:00+00:00"}}
/api/daybook/v1/appointments/{id}/cancel
Needs READ-WRITE
— Cancel an appointment, for your organisation
Answers 202. You cancel as the organisation, so the customer is refunded in full whatever your cancellation policy says, and is told the reason you give. It becomes final at final_at — the end of your undo window — and APPOINTMENT-CANCELLED is sent then. 409 NOT-ALLOWED when it cannot be cancelled now.
curl
curl -X POST https://www.drivebird.com/api/daybook/v1/appointments/501/cancel -H "Authorization: Bearer daybook_…" -H "Content-Type: application/json" \
-d '{"reason": "The dentist is unwell."}'
PHP (Laravel Http)
Http::withToken($key)->post('https://www.drivebird.com/api/daybook/v1/appointments/501/cancel', ['reason' => 'The dentist is unwell.']); // 202
Response
{"data": {"appointment": { …appointment, still CONFIRMED until final_at… }, "cancellation": {"fee_minor": 0, "refund_minor": 50000, "currency": "INR", "final_at": "2026-09-12T06:01:30+00:00"}}}
/api/daybook/v1/people?search=&page=&per_page=
Needs READ
— Your customers, by name
search matches a name, an email address or a phone number.
curl
curl "https://www.drivebird.com/api/daybook/v1/people?search=priya" -H "Authorization: Bearer daybook_…"
PHP (Laravel Http)
$people = Http::withToken($key)->get('https://www.drivebird.com/api/daybook/v1/people', ['search' => 'priya'])->json('data');
Response
{"data":[{"id":77,"name":"Priya Sharma","email":"priya@example.com","phone":null,"timezone":"Asia/Kolkata","locale":"en","created_at":"2026-09-11T03:30:00+00:00"}],"meta":{"page":1,"per_page":25,"total":1,"last_page":1}}
/api/daybook/v1/people/{id}
Needs READ
— One customer
curl
curl https://www.drivebird.com/api/daybook/v1/people/77 -H "Authorization: Bearer daybook_…"
PHP (Laravel Http)
$person = Http::withToken($key)->get('https://www.drivebird.com/api/daybook/v1/people/77')->json('data');
Response
{"data":{"id":77,"name":"Priya Sharma","email":"priya@example.com","phone":null,"timezone":"Asia/Kolkata","locale":"en","created_at":"2026-09-11T03:30:00+00:00"}}
For assistants booking for a person
An assistant acting for a person — another company's — may ask to book with an organisation that has switched this on.
No key is needed, and asking books nothing: the time is held for
60 minutes
and the person is emailed a link; only their own "yes" books it. Each organisation sets how many requests one email
address may make in a day. {organisation} is the
organisation's booking address, as in /daybook/book/bright-clinic.
- •
GET https://www.drivebird.com/api/daybook/v1/assistants/{organisation}— the rules, and the services that can be asked for, with who offers each. - •
GET https://www.drivebird.com/api/daybook/v1/assistants/{organisation}/times?service_id=12&from=2026-09-14&days=7— free times, up to 14 days. - •
POST https://www.drivebird.com/api/daybook/v1/assistants/{organisation}/requests—assistant(your name),service_id,member_id,starts_at, the person'snameandemail, optionalphone. 202 when the person has been emailed; 409 SLOT-TAKEN; 429 RATE-LIMITED past the day's limit.
curl -X POST https://www.drivebird.com/api/daybook/v1/assistants/bright-clinic/requests \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"assistant":"Acme Concierge","service_id":12,"member_id":4,"starts_at":"2026-09-14T04:00:00+00:00","name":"Priya Sharma","email":"priya@example.com"}'
Webhooks
Add up to 5 https addresses on the API & webhooks screen and tick what each one should be told. Each gets its own signing secret, shown once. We never call a private or local address.
| Event | Sent when |
|---|---|
APPOINTMENT-BOOKED |
A booking is made through any door — your booking page, your desk, this API, the waiting list. For a place in a class, data.appointment is the class and data.joined_class is true. |
APPOINTMENT-CANCELLED |
An appointment is cancelled. Sent when it is final, after the undo window, so a cancellation taken back is never sent. |
APPOINTMENT-MOVED |
An appointment's time changes. data.previous_starts_at is the time it left. |
PAYMENT-PAID |
Money from a customer arrives. data.payment is the payment; data.appointment is null for a package bought on its own. |
REFUND-SENT |
A refund is sent back to a customer. data.payment is the refund. |
The body
{"id":9001,"event":"APPOINTMENT-MOVED","created_at":"2026-09-12T06:00:00+00:00","organisation":{"id":3,"slug":"bright-clinic"},"data":{"appointment":{"id":501,"state":"CONFIRMED","confirmation_mark":"NOT-ASKED","source":"API","service":{"id":12,"name":"Check-up"},"member":{"id":4,"name":"Asha Rao"},"starts_at":"2026-09-14T05:30:00+00:00","ends_at":"2026-09-14T06:00:00+00:00","timezone":"Asia/Kolkata","price_minor":50000,"deposit_minor":0,"currency":"INR","meeting_mode":"IN-PERSON","meeting_url":null,"capacity":1,"booked_count":1,"people":[{"participation_id":1201,"person_id":77,"name":"Priya Sharma","email":"priya@example.com","phone":null,"role":"BOOKER","left_at":null}],"cancelled_at":null,"cancelled_by":null,"cancel_reason":null,"cancel_final_at":null,"rebooked_from_id":null,"series_id":null,"created_at":"2026-09-11T03:30:00+00:00"},"previous_starts_at":"2026-09-14T04:30:00+00:00"}}
The headers
- •
X-DriveBird-Event— the event, as in the body. - •
X-DriveBird-Delivery— the delivery's id. The same delivery can arrive twice; it carries the same id each time, so keep the ones you have handled. - •
X-DriveBird-Timestamp— when it was sent, in Unix seconds. - •
X-DriveBird-Signature—sha256=and the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with your secret.
Checking the signature
Compute the signature from the raw body, compare it in constant time, and refuse a timestamp more than five minutes old:
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_DRIVEBIRD_TIMESTAMP'] ?? '';
$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$body, $secret);
if (! hash_equals($expected, $_SERVER['HTTP_X_DRIVEBIRD_SIGNATURE'] ?? '') || abs(time() - (int) $timestamp) > 300)
{
http_response_code(401);
exit;
}
Answering, retries and order
- • Answer any 2xx within 10 seconds. Redirects are not followed.
- • Anything else is tried again after 1 min, 5 min, 30 min, 2 h, 6 h — 6 attempts in all — and then given up.
- • After 3 events in a row have been given up, the address is paused and the organisation's owner is emailed. Nothing is sent to a paused address, and events that happen meanwhile are not kept, until it is resumed on the API & webhooks screen.
- • Events can arrive out of order. When the latest state matters, read the appointment.
- • The screen lists the last 20 deliveries with the answer each got; the log is kept 30 days.
Error codes
| Status | code | When |
|---|---|---|
| 401 | UNAUTHENTICATED | The Authorization: Bearer key is missing, malformed or revoked. |
| 403 | KEY-SCOPE-MISSING | The key is READ only and the call books or cancels. Make a READ-WRITE key on your organisation's API & webhooks screen. |
| 403 | ORGANISATION-CLOSED | The organisation is suspended or closed, so its API answers nothing until it is active again. |
| 422 | VALIDATION | A parameter is missing or malformed (see errors[]). |
| 409 | SLOT-TAKEN | That time is no longer free — somebody booked it, or the hours changed. Ask for free times again. |
| 409 | NOT-ALLOWED | The appointment cannot be cancelled now: it is already being cancelled, it is over, or cancelling is switched off for the host. |
| 410 | GONE | No such service, member, length, appointment or customer for this organisation. DriveBird never answers 404. |
| 429 | RATE-LIMITED | More than 120 requests a minute for your organisation, or 300 from one IP address. |
| 500 | SERVER-ERROR | Something failed on our side and nothing was changed. Try again in a minute. |