Getting started

Everything every Booker API call has in common: the key, the address, the response shape and what the errors mean.

API keys

Booker gives your company an API key. Send it on every request as a bearer token:

Authorization: Bearer $BOOKER_API_KEY

A key acts for your whole company, with an owner's permissions. Keep it on your server or in your voice platform's server-side tool settings. Never put it in a web page, a mobile app or anywhere a caller or a model could read it. If a key leaks, ask Booker to revoke it and issue a new one.

Base URL

Every endpoint is under /api/v1 on your Booker API host:

https://api.example.com/api/v1

Booker will confirm your host when you get access. Request and response bodies are JSON (Content-Type: application/json).

Responses

Most responses share one envelope. A success has success: true and usually data; some also carry a message or warnings:

{ "success": true, "data": { … } }

A failure has success: false and a readable message you can show or say:

{ "success": false, "message": "Not eligible for this appointment type" }

The one exception is conversation-init, which answers in ElevenLabs' conversation-initiation format. Timestamps such as start_time are ISO 8601 in UTC. The startTimeLocal, endTimeLocal, local_start_time and local_end_time fields are local times written YYYY-MM-DD HH:mm:ss in the given timezone (an IANA name). The provider's time zone governs their schedule and the slots they offer.

Errors and retries

Status	Meaning	What to do
400	The request is invalid: a missing field, a bad date, a time that breaks a booking rule.	Read `message`, fix the request or ask the caller for something else.
401	The API key is wrong (`Invalid credentials`), or an agent session expired (`Session expired`).	Check the key. For agents, start a new conversation.
403	Not allowed, for example: the caller may not book this, or isn't identified yet.	Don't retry. The `message` says why.
404	Not found. Another company's ids are always “not found”.	Check the id.
409	A conflict, for example: the slot was just taken, or the record already exists.	Offer another slot, or use the existing record.
429	A limit was reached (verification codes, address saves).	Don't retry in the same conversation.
502	A text message couldn't be sent.	Try again later.
503	The provider's calendar couldn't be checked. Nothing was booked or changed.	Safe to retry after a moment.
500	Something went wrong on Booker's side.	For a read, retry once. For a booking, reschedule or cancel, treat it like a timeout: list the caller's appointments before retrying. If it persists, contact support.

Timeouts

Booker has no idempotency keys. If a booking request times out, you can't tell whether it went through. Before retrying, list the caller's appointments (List the caller's upcoming appointments) and only book again if the appointment isn't there.

Wiring an AI agent? Read Agent integration. Every endpoint, with examples you can try, is in the API reference.