Developer docs menu
Getting started
How a booking is made
Holds, the customer’s confirmation, and what to do when a booking needs the customer.
The order
Profile, services and requirements: find out what to ask.
Quote: get the real price from the customer’s answers.
Availability: find free times.
Hold, if the customer needs a moment to decide.
Tell the customer the price and the time, and get their yes.
Booking.
Holding a time
POST /businesses/{slug}/holds with a slotId keeps the time for 10 minutes, or up to 15 with ttlMinutes. Put the holdToken on the booking. To give the time back early, DELETE /businesses/{slug}/holds/{token}. A hold is optional: a booking can be made straight from a slotId.
Without an API key: the customer confirms
A booking asked for without a key answers 202 with status: "awaiting_customer_confirmation". The customer is emailed a link and has 60 minutes to press Confirm (confirmBy). Until they do, nothing is booked and the business is not told. Tell the customer to check their email.
GET /businesses/{slug}/bookings/{id} shows where it stands:
| status | Meaning |
|---|---|
| awaiting_customer_confirmation | The customer has been emailed. Nothing is booked yet. |
| confirmed | The booking exists. bookingStatus says how the business has it: confirmed, or pending_confirmation when the business approves each booking itself. |
| expired | The customer did not confirm in time. Nothing was booked. |
| failed | The customer said yes but the booking could not be made. failureCode says why, most often that the time had gone. |
With the business’s API key: booked directly
A request that carries the business’s own key with the write:bookings scope answers 201 with status: "confirmed". The booking is made at once, by the same steps as the booking form, and the customer gets the business’s usual confirmation email. See API keys.
When the customer has to do it themselves
Some businesses take payment, or ask for signed documents, when a booking is made. The API cannot do either for a customer. The refusal is 409 requires_action, details.reason is payment or documents, and details.bookingUrl is the page to send the customer to.
Retries
Send an Idempotency-Key header on a hold or a booking: a value of your own, 1 to 255 characters, unique to this attempt. A retry with the same key and the same body gets the first answer back, with Idempotent-Replayed: true, and the work is not done twice.
Limits on confirmation emails
A booking without a key sends an email to an address the caller chose, so it is limited: a few a day to one address, and ceilings per caller, per business and for the whole platform. Past a limit the refusal is 429 with customer_confirmation_limit or booking_requests_limit. One hold can carry one waiting request at a time (409 hold_in_use). Bookings made with a key are not limited this way.
Still have questions? Contact support