Quickstart
Book an appointment from your agent in three steps. These examples use cURL.
You’ll need a Booker company with a phone number, an API key, and a provider. Connecting the provider's calendar is recommended; without one, booking still works and the response says calendar_integration.status is not_configured.
Authenticate
Send your API key as a bearer token on every request. Keep it on your server or in your voice platform's server-side settings, never where a caller or a model could read it.
export BOOKER_API_KEY="••••••••"Start a session
Your voice platform calls conversation-init when a call starts. Booker identifies the caller and returns a session_id for every later call. It's a webhook, never a tool the model can call.
/api/v1/agent/conversation-initStart a conversation{
"type": "conversation_initiation_client_data",
"dynamic_variables": {
"session_id": "BU7Wp_xnB8e5b6LEyCERvMX6scsZHglpIkQIB36S6IU",
"customer_first_name": "Dana",
"bookable_types": "Site Survey, Panel Inspection"
}
}Find a slot and book it
Search for slots and offer the recommended ones first. Book the one the caller picks. Booker checks the provider's calendar live before booking.
/api/v1/agent/slotsFind slots/api/v1/agent/appointmentsBook a slotIdentifying new callers, addresses, rescheduling and what the agent can see are in Agent integration.
API reference
Every endpoint with its requests, responses and examples. Try requests against your own Booker API.
Errors and retries
Failures are { "success": false, "message": … } with a readable message. A 503 means the calendar couldn't be checked and nothing was booked: safe to retry. There are no idempotency keys, so after a timeout list the caller's appointments before booking again.