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-cleaning

The 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/services

Each 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/requirements

This 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.

Info: Send X-Agent with your agent’s name on every request. It is kept on any booking you make, so the business can see where it came from.

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