Developer docs menu
Getting started
Quickstart
Price a job and book it for a customer in six calls.
The API lets your software, or an AI assistant, do what a customer does on a business’s booking page: see what it sells, get the real price for a job, find a free time and book it. Reading needs no API key. The examples use fresh-start-cleaning, the sandbox. For a real business, use its slug, the last part of its booking page address.
1. Read the business
curl https://api.bookingmachine.io/v1/businesses/fresh-start-cleaningThe answer has its timezone, currency, opening hours and booking rules, and capabilities: what the API will do for this business right now.
2. List its services
curl https://api.bookingmachine.io/v1/businesses/fresh-start-cleaning/servicesEach service has an id, a length and a basePrice. The base price is not the price: the customer’s answers change it.
3. Ask what the service needs to know
curl https://api.bookingmachine.io/v1/businesses/fresh-start-cleaning/services/SERVICE_ID/requirementsThis lists the questions that set the price (dimensions), any other questions, the add-ons on offer, and whether an address is needed. Ask the customer these.
4. Get the real price
curl -X POST https://api.bookingmachine.io/v1/businesses/fresh-start-cleaning/quotes \
-H 'Content-Type: application/json' \
-d '{
"serviceIds": ["SERVICE_ID"],
"answers": { "bedrooms": "three", "bathrooms": "two" }
}'The price is worked out by the business’s own pricing rules, exactly as its booking form does. Nothing is saved and nobody is told, so ask again whenever an answer changes. If an answer is missing, the refusal is answers_invalid and details.issues lists what still has to be asked.
5. Find a free time
curl 'https://api.bookingmachine.io/v1/businesses/fresh-start-cleaning/availability?serviceId=SERVICE_ID&date=2026-12-01'Only free times are listed. Each has an id, good for 24 hours, to hold or book it with. start and end are UTC. Tell the customer the time on the business’s own clock, which is timezone.
6. Book it
curl -X POST https://api.bookingmachine.io/v1/businesses/fresh-start-cleaning/bookings \
-H 'Content-Type: application/json' \
-H 'X-Agent: Acme Receptionist' \
-H 'Idempotency-Key: 7f3c1e0a-booking-1' \
-d '{
"serviceIds": ["SERVICE_ID"],
"slotId": "SLOT_ID",
"answers": { "bedrooms": "three", "bathrooms": "two" },
"customer": { "name": "Alex Kim", "email": "[email protected]" }
}'Without an API key the answer is 202 with status: "awaiting_customer_confirmation". The customer is emailed a link, and the booking is made when they press Confirm. Read How a booking is made for what happens next.
fresh-start-cleaning is the sandbox: it emails nobody and never makes a booking, so the request stays waiting. Sandbox shows how to play the customer’s part.
Where to go next
Sandbox: the practice business these examples use.
Concepts: money, time, and the words the API uses.
API keys: acting for a business with its own key.
MCP server: give the same operations to an AI assistant as tools.
API reference: every operation.
Still have questions? Contact support