Developer docs menu

Reference

API reference

Every operation, what it takes and what it answers. This page is drawn from the live OpenAPI document.

Base address: https://api.bookingmachine.io/v1. OpenAPI 3.1: openapi.json

Businesses

Who a business is, what it sells and what it needs to know.

get/businesses/{slug}

A business’s profile

Who the business is, where and when it works, its booking rules, its rating, and what this API will do for it right now (capabilities).

Needs: No key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.

Answers

  • 200 The profile.
    Fields of data
    FieldTypeNotes
    slugstringRequired.
    namestringRequired.
    verticalobjectRequired.
    phonestring or nullRequired.
    emailstring or nullRequired.
    addressobject or nullRequired.
    locationsarray of objectRequired.
    timezonestringRequired.
    currencystringRequired.
    localestringRequired.
    countrystringRequired.
    openingHoursarray of objectRequired.
    policiesobjectRequired.
    reviewsobjectRequired.
    bookingUrlstringRequired.
    sandboxbooleanRequired.
    capabilitiesobjectRequired.
  • 401 api_key_invalid
  • 403 agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed
  • 404 business_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/businesses/{slug}/services

The services on sale

Each service with its length and base price before the customer’s answers change them. Never quote basePrice as the price: ask for a quote.

Needs: No key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.

Answers

  • 200 The services.
    Fields of data
    FieldTypeNotes
    currencystringRequired.
    servicesarray of objectRequired.
  • 401 api_key_invalid
  • 403 agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed
  • 404 business_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/businesses/{slug}/services/{serviceId}/requirements

What must be answered to price and book a service

The options that set the price (dimensions), the questions, the add-ons, and whether an address, payment or documents are needed. Ask the customer these before asking for a quote.

Needs: No key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.
serviceIdstring (uuid)Required. In the path. A service id from the services list.
withstringIn the query. Other services booked with it, comma-separated; their options, questions and add-ons are then included.

Answers

  • 200 The requirements.
    Fields of data
    FieldTypeNotes
    serviceobjectRequired.
    dimensionsarray of objectRequired.
    questionsarray of objectRequired.
    bookingFieldsarray of objectRequired.
    addonsarray of objectRequired.
    addressobjectRequired.
    teamMemberobjectRequired.
    recurringobjectRequired.
    paymentobjectRequired.
    confirmationMode"auto" | "manual"Required.
    cancellationobjectRequired.
    documentsarray of objectRequired.
    currencystringRequired.
    timezonestringRequired.
    localestringRequired.
  • 401 api_key_invalid
  • 403 agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed
  • 404 service_not_found, business_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off

Prices and times

A real price and real free times.

post/businesses/{slug}/quotes

The real price for what the customer wants

Worked out by the business’s own pricing rules, exactly as its booking form does. Nothing is saved and nobody is notified, so ask again whenever an answer changes. A missing or impossible answer is a 422 answers_invalid whose details.issues lists what still has to be asked.

Needs: No key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.

Body

FieldTypeNotes
serviceIdsarray of string (uuid)Required. up to 20 items
answersobject
addonsarray of stringup to 50 items
datestring
checkInDatestring
checkOutDatestring
hoursinteger1 to 24
recurringFrequency"weekly" | "biweekly" | "monthly"
voucherCodestringup to 32 characters

Answers

  • 200 The price.
    Fields of data
    FieldTypeNotes
    currencystringRequired.
    totalnumberRequired.
    subtotalnumberRequired.
    discountnumberRequired.
    lineItemsarray of objectRequired.
    depositnumberRequired.
    balancenumberRequired.
    durationMinutesnumberRequired.
  • 400 invalid_request, units_invalid, addon_not_offered
  • 401 api_key_invalid
  • 403 agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed
  • 404 service_not_found, business_not_found
  • 422 answers_invalid
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/businesses/{slug}/availability

The times a customer can book

Only free times are listed, each with a signed id (good for 24 hours) to hold or book it with. start and end are UTC instants; tell the customer the time on the business’s clock (timezone). Give date, or from and to for up to 31 days.

Needs: No key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.
serviceIdstring (uuid)Required. In the query. The service.
withstringIn the query. Other services booked with it, comma-separated.
datestringIn the query. One day, in the business’s zone.
fromstringIn the query. The first day of a range.
tostringIn the query. The last day of a range, at most 31 days from from.
addonsstringIn the query. Add-on keys, comma-separated: they lengthen the job.
hoursintegerIn the query. How many hours, for a service sold by the hour. 1 to 24
teamMemberIdstring (uuid)In the query. Only this team member’s times.
locationIdstring (uuid)In the query. Only this location’s times.

Answers

  • 200 The free times, day by day.
    Fields of data
    FieldTypeNotes
    timezonestringRequired.
    durationMinutesnumberRequired.
    daysarray of objectRequired.
  • 400 invalid_request, range_invalid, stays_not_supported
  • 401 api_key_invalid
  • 403 agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed
  • 404 service_not_found, location_not_found, business_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off

Booking

Holding a time and booking it.

post/businesses/{slug}/holds

Keep a time while the customer decides

The time is off offer to everyone else for 10 minutes (15 at most). Put the holdToken on the booking. One caller can hold three times at once and a business twelve in all.

Needs: No key, or a key with the write:bookings scope. Takes Idempotency-Key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.

Body

FieldTypeNotes
slotIdstringRequired. up to 1024 characters
ttlMinutesinteger1 to 15

Answers

  • 201 The hold.
    Fields of data
    FieldTypeNotes
    holdTokenstringRequired.
    slotIdstringRequired.
    startstringRequired.
    endstringRequired.
    expiresAtstringRequired.
    timezonestringRequired.
  • 400 invalid_request, slot_invalid, idempotency_key_invalid
  • 401 api_key_invalid
  • 403 bookings_paused, agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed, agent_writes_off, agent_bookings_not_in_plan, agent_bookings_off_for_business, scope_missing
  • 404 business_not_found
  • 409 slot_unavailable
  • 429 too_many_holds, rate_limited
  • 500 internal_error
  • 503 agent_platform_off
delete/businesses/{slug}/holds/{token}

Let a hold go early

The token is the only proof of whose hold it is.

Needs: No key, or a key with the write:bookings scope.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.
tokenstringRequired. In the path. The holdToken.

Answers

  • 200 The time is on offer again.
  • 401 api_key_invalid
  • 403 agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed, agent_writes_off, agent_bookings_not_in_plan, agent_bookings_off_for_business, scope_missing
  • 404 hold_invalid, business_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/businesses/{slug}/bookings

Book for a customer

Without an API key this asks for a booking: the request is checked exactly as a booking would be, the time is held, and the customer is emailed a link. The answer is 202 awaiting_customer_confirmation, and the booking is made only when the customer confirms; until then the business hears nothing. With the business’s own key (scope write:bookings) the booking is made there and then: 201 confirmed. What only a person can do (pay up front, accept the business’s documents) is answered with 409 requires_action, with details.reason and the details.bookingUrl to send the customer to.

Needs: No key, or a key with the write:bookings scope. Takes Idempotency-Key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.

Body

FieldTypeNotes
serviceIdsarray of string (uuid)Required. up to 10 items
slotIdstringup to 1024 characters
holdTokenstringup to 128 characters
answersobject
addonsarray of stringup to 50 items
hoursinteger1 to 24
recurringFrequency"weekly" | "biweekly" | "monthly"
voucherCodestringup to 32 characters
customerobjectRequired.
notesstringup to 2000 characters

Answers

  • 202 Asked for: the customer has been emailed to confirm.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    status"awaiting_customer_confirmation" | "confirmed" | "expired" | "failed"Required.
    serviceNamestringRequired.
    startstringRequired.
    endstringRequired.
    timezonestringRequired.
    currencystringRequired.
    totalnumberRequired.
    confirmBystring or nullRequired.
    heldUntilstring or nullRequired.
    bookingStatusstring or nullRequired.
    sandboxboolean
    bookingIdstring or null
    failureCodestring or nullRequired.
  • 201 Booked (a key with write:bookings).
    Fields of data
    FieldTypeNotes
    idstringRequired.
    status"awaiting_customer_confirmation" | "confirmed" | "expired" | "failed"Required.
    serviceNamestringRequired.
    startstringRequired.
    endstringRequired.
    timezonestringRequired.
    currencystringRequired.
    totalnumberRequired.
    confirmBystring or nullRequired.
    heldUntilstring or nullRequired.
    bookingStatusstring or nullRequired.
    sandboxboolean
    bookingIdstring or null
    failureCodestring or nullRequired.
  • 400 invalid_request, slot_invalid, hold_invalid, orders_not_supported, addon_not_offered, idempotency_key_invalid
  • 401 api_key_invalid
  • 403 bookings_paused, agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed, agent_writes_off, agent_bookings_not_in_plan, agent_bookings_off_for_business, scope_missing
  • 404 service_not_found, business_not_found
  • 409 slot_unavailable, hold_expired, hold_in_use, requires_action, already_booked, closed_dates, service_not_offered, voucher_depleted
  • 422 answers_invalid, address_incomplete, address_partial, address_outside_region
  • 429 too_many_holds, customer_confirmation_limit, booking_requests_limit, rate_limited
  • 500 internal_error
  • 502 email_failed
  • 503 agent_platform_off
get/businesses/{slug}/bookings/{id}

How a booking asked for through the API went

awaiting_customer_confirmation, confirmed, expired or failed. The answer never holds the customer’s details.

Needs: No key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.
idstring (uuid)Required. In the path. The id the booking request was answered with.

Answers

  • 200 The booking request as it stands.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    status"awaiting_customer_confirmation" | "confirmed" | "expired" | "failed"Required.
    serviceNamestringRequired.
    startstringRequired.
    endstringRequired.
    timezonestringRequired.
    currencystringRequired.
    totalnumberRequired.
    confirmBystring or nullRequired.
    heldUntilstring or nullRequired.
    bookingStatusstring or nullRequired.
    sandboxboolean
    bookingIdstring or null
    failureCodestring or nullRequired.
  • 401 api_key_invalid
  • 403 agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed
  • 404 booking_not_found, business_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/businesses/{slug}/bookings/{id}/simulate

Sandbox only: play the customer’s part

The sandbox emails nobody, so a booking asked for there waits for a confirmation that never comes. This settles it as the customer would: confirmed (the default) or expired. Nothing is booked. On any real business the answer is 403 sandbox_only.

Needs: No key, or a key with the write:bookings scope.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.
idstring (uuid)Required. In the path. The id the booking request was answered with.

Body (may be left out)

FieldTypeNotes
outcome"confirmed" | "expired"

Answers

  • 200 The booking request as it now stands.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    status"awaiting_customer_confirmation" | "confirmed" | "expired" | "failed"Required.
    serviceNamestringRequired.
    startstringRequired.
    endstringRequired.
    timezonestringRequired.
    currencystringRequired.
    totalnumberRequired.
    confirmBystring or nullRequired.
    heldUntilstring or nullRequired.
    bookingStatusstring or nullRequired.
    sandboxboolean
    bookingIdstring or null
    failureCodestring or nullRequired.
  • 400 invalid_request
  • 401 api_key_invalid
  • 403 sandbox_only, agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed, agent_writes_off, agent_bookings_not_in_plan, agent_bookings_off_for_business, scope_missing
  • 404 booking_not_found, business_not_found
  • 409 booking_not_waiting
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off

Reviews

get/businesses/{slug}/reviews

The reviews a business publishes

Newest first, a page at a time. summary covers every published review, not only the page.

Needs: No key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.
limitintegerIn the query. How many, 1 to 50. 1 to 50
cursorstringIn the query. nextCursor of the page before.
verifiedbooleanIn the query. true for only reviews that followed a completed booking.

Answers

  • 200 A page of reviews.
    Fields of data
    FieldTypeNotes
    summaryobjectRequired.
    timezonestringRequired.
    reviewsarray of objectRequired.
    nextCursorstring or nullRequired.
  • 400 invalid_request, cursor_invalid
  • 401 api_key_invalid
  • 403 agents_off_for_business, api_keys_off, api_key_wrong_business, api_access_not_in_plan, partner_suspended, partner_wrong_business, partner_access_removed
  • 404 business_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off

Account

The business’s own records, for its own software. An API key is required.

get/account

The business an API key belongs to

The business, and what the key may do. Needs no scope, so it is the call to check a key with.

Needs: The business’s API key.

Answers

  • 200 The business and the key.
    Fields of data
    FieldTypeNotes
    businessobjectRequired.
    keyobjectRequired.
  • 400 business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/account/bookings

The business’s own bookings

Every booking the business has, however it was made, the newest made first, with the customer on each.

Needs: The business’s API key, with the read:bookings scope.

Parameters

FieldTypeNotes
status"pending_payment" | "pending_confirmation" | "confirmed" | "in_progress" | "completed" | "cancelled" | "no_show"In the query. Only bookings with this status.
fromstringIn the query. Bookings that start on or after this day, in the business’s zone.
tostringIn the query. Bookings that start on or before this day.
createdSincestring (date-time)In the query. Bookings made at or after this instant.
customerIdstring (uuid)In the query. One customer’s bookings.
limitintegerIn the query. How many, 1 to 50. 1 to 50
cursorstringIn the query. nextCursor of the page before.

Answers

  • 200 A page of bookings.
    Fields of data
    FieldTypeNotes
    timezonestringRequired.
    currencystringRequired.
    bookingsarray of objectRequired.
    nextCursorstring or nullRequired.
  • 400 invalid_request, cursor_invalid, business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/account/bookings/{id}

One of the business’s bookings

By the booking’s own id: bookingId on a booking made with the key, or id in the bookings list.

Needs: The business’s API key, with the read:bookings scope.

Parameters

FieldTypeNotes
idstring (uuid)Required. In the path. The booking’s id.

Answers

  • 200 The booking.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    statusstringRequired.
    paymentStatusstringRequired.
    serviceIdstring or nullRequired.
    serviceNamestring or nullRequired.
    startstringRequired.
    endstringRequired.
    durationMinutesnumberRequired.
    nightsnumber or nullRequired.
    totalnumberRequired.
    depositnumberRequired.
    balancenumberRequired.
    recurringFrequencystring or nullRequired.
    notesstring or nullRequired.
    customerobjectRequired.
    channelstring or nullRequired.
    agentNamestring or nullRequired.
    customerUrlstring or nullRequired.
    createdAtstringRequired.
    updatedAtstringRequired.
  • 400 business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 404 booking_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/account/customers

The business’s customers

As the business has them. email finds one customer by their exact address.

Needs: The business’s API key, with the read:customers scope.

Parameters

FieldTypeNotes
emailstringIn the query. The customer with exactly this address.
qstringIn the query. Customers whose name or email contains this.
limitintegerIn the query. How many, 1 to 50. 1 to 50
cursorstringIn the query. nextCursor of the page before.

Answers

  • 200 A page of customers.
    Fields of data
    FieldTypeNotes
    currencystringRequired.
    customersarray of objectRequired.
    nextCursorstring or nullRequired.
  • 400 invalid_request, cursor_invalid, business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/account/bookings/{id}/status

Move a booking on

confirm or decline a request, start, complete, cancel, or no_show. The same change as the button in the dashboard, with everything that follows it: the customer’s email, and whatever the business has set up for a completed job (invoice, review request, balance charge), a cancellation (refund by its policy) or a no-show (fee).

Needs: The business’s API key, with the write:bookings scope. Takes Idempotency-Key.

Parameters

FieldTypeNotes
idstring (uuid)Required. In the path. The booking’s id.

Body

FieldTypeNotes
action"confirm" | "decline" | "start" | "complete" | "cancel" | "no_show"Required.
reasonstringup to 500 characters

Answers

  • 200 The booking as it now is.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    statusstringRequired.
    paymentStatusstringRequired.
    serviceIdstring or nullRequired.
    serviceNamestring or nullRequired.
    startstringRequired.
    endstringRequired.
    durationMinutesnumberRequired.
    nightsnumber or nullRequired.
    totalnumberRequired.
    depositnumberRequired.
    balancenumberRequired.
    recurringFrequencystring or nullRequired.
    notesstring or nullRequired.
    customerobjectRequired.
    channelstring or nullRequired.
    agentNamestring or nullRequired.
    customerUrlstring or nullRequired.
    createdAtstringRequired.
    updatedAtstringRequired.
  • 400 invalid_request, idempotency_key_invalid, business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 404 booking_not_found
  • 409 booking_status_conflict
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/account/bookings/{id}/reschedule

Move a booking to a new time

The new time must be free by the rules a customer booking meets; take it from availability (slotId) or send start. The price is worked out again: if it changes, the answer is 409 price_changed with newTotal, and the same request with confirmTotal set to it goes ahead. The customer is emailed the new time, as when the business moves it in the dashboard.

Needs: The business’s API key, with the write:bookings scope. Takes Idempotency-Key.

Parameters

FieldTypeNotes
idstring (uuid)Required. In the path. The booking’s id.

Body

FieldTypeNotes
slotIdstringup to 1024 characters
startstring (date-time)
confirmTotalnumber0 or more

Answers

  • 200 The booking as it now is.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    statusstringRequired.
    paymentStatusstringRequired.
    serviceIdstring or nullRequired.
    serviceNamestring or nullRequired.
    startstringRequired.
    endstringRequired.
    durationMinutesnumberRequired.
    nightsnumber or nullRequired.
    totalnumberRequired.
    depositnumberRequired.
    balancenumberRequired.
    recurringFrequencystring or nullRequired.
    notesstring or nullRequired.
    customerobjectRequired.
    channelstring or nullRequired.
    agentNamestring or nullRequired.
    customerUrlstring or nullRequired.
    createdAtstringRequired.
    updatedAtstringRequired.
  • 400 invalid_request, idempotency_key_invalid, slot_invalid, no_change, business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 404 booking_not_found
  • 409 booking_status_conflict, slot_unavailable, price_changed
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/account/webhooks

The business’s webhook endpoints

And every event an endpoint can ask for. Signing secrets are never listed.

Needs: The business’s API key, with the manage:webhooks scope.

Answers

  • 200 The endpoints.
    Fields of data
    FieldTypeNotes
    webhooksarray of objectRequired.
    eventsarray of stringRequired.
  • 400 business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/account/webhooks

Add a webhook endpoint

A public https address that is sent the events it asks for (["*"] for all). The answer carries secret, once: each delivery is signed with it (X-BookingMachine-Signature is sha256= and the HMAC-SHA256 of <X-BookingMachine-Timestamp>.<body>). A business can have five endpoints.

Needs: The business’s API key, with the manage:webhooks scope.

Body

FieldTypeNotes
urlstringRequired. up to 2000 characters
eventsarray of stringRequired.
descriptionstringup to 200 characters

Answers

  • 201 Added. secret is not shown again.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    urlstringRequired.
    descriptionstring or nullRequired.
    eventsarray of stringRequired.
    activebooleanRequired.
    createdAtstringRequired.
    secretstringRequired.
  • 400 invalid_request, business_required
  • 401 api_key_required, api_key_invalid
  • 403 webhooks_off, webhooks_not_in_plan, api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 409 webhook_limit
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
delete/account/webhooks/{id}

Remove a webhook endpoint

Nothing more is sent to it, and its delivery log goes with it.

Needs: The business’s API key, with the manage:webhooks scope.

Parameters

FieldTypeNotes
idstring (uuid)Required. In the path. The endpoint’s id.

Answers

  • 200 Removed.
  • 400 business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 404 webhook_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/account/customers/{id}

One of the business’s customers

By the customer’s id.

Needs: The business’s API key, with the read:customers scope.

Parameters

FieldTypeNotes
idstring (uuid)Required. In the path. The customer’s id.

Answers

  • 200 The customer.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    namestringRequired.
    emailstring or nullRequired.
    phonestring or nullRequired.
    tagsarray of stringRequired.
    bookingCountintegerRequired.
    lifetimeValuenumberRequired.
    firstBookedAtstring or nullRequired.
    lastBookedAtstring or nullRequired.
  • 400 business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 404 customer_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/account/customers

Find a customer by email, or add them

A customer the business already has under that email comes back unchanged (200, created: false). Otherwise they are added (201). Without an email there is nothing to find by, so a customer is always added.

Needs: The business’s API key, with the write:customers scope. Takes Idempotency-Key.

Body

FieldTypeNotes
namestringRequired. up to 255 characters
emailstring (email)up to 255 characters
phonestringup to 50 characters
notesstringup to 5000 characters
tagsarray of stringup to 20 items

Answers

  • 200 The business already had them.
    Fields of data
    FieldTypeNotes
    createdbooleanRequired.
    customerobjectRequired.
  • 201 Added.
    Fields of data
    FieldTypeNotes
    createdbooleanRequired.
    customerobjectRequired.
  • 400 invalid_request, idempotency_key_invalid, business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/account/quotes

The business’s quotes

The quotes it wrote, the ones customers asked for, and booking forms left unfinished (abandoned), the newest made first.

Needs: The business’s API key, with the read:quotes scope.

Parameters

FieldTypeNotes
status"pending" | "sent" | "accepted" | "expired" | "converted" | "declined"In the query. Only quotes with this status.
createdSincestring (date-time)In the query. Quotes made at or after this instant.
customerIdstring (uuid)In the query. One customer’s quotes.
limitintegerIn the query. How many, 1 to 50. 1 to 50
cursorstringIn the query. nextCursor of the page before.

Answers

  • 200 A page of quotes.
    Fields of data
    FieldTypeNotes
    timezonestringRequired.
    currencystringRequired.
    quotesarray of objectRequired.
    nextCursorstring or nullRequired.
  • 400 invalid_request, cursor_invalid, business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/account/quotes/{id}

One of the business’s quotes

By the quote’s id.

Needs: The business’s API key, with the read:quotes scope.

Parameters

FieldTypeNotes
idstring (uuid)Required. In the path. The quote’s id.

Answers

  • 200 The quote.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    statusstringRequired.
    serviceIdstring or nullRequired.
    serviceNamestring or nullRequired.
    lineItemsarray of objectRequired.
    subtotalnumberRequired.
    discountnumberRequired.
    totalnumberRequired.
    customerobject or nullRequired.
    notesstring or nullRequired.
    checkInstring or nullRequired.
    checkOutstring or nullRequired.
    datestring or nullRequired.
    hoursnumber or nullRequired.
    validUntilstring or nullRequired.
    sentAtstring or nullRequired.
    bookingIdstring or nullRequired.
    channelstring or nullRequired.
    abandonedbooleanRequired.
    quoteUrlstringRequired.
    createdAtstringRequired.
    updatedAtstringRequired.
  • 400 business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 404 quote_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/account/quotes

Write a quote for a customer

Priced by the business’s own rules, saved to its Quotes, and with send: true emailed to the customer with a link to book it. The same quote the dashboard’s "New quote" makes.

Needs: The business’s API key, with the write:quotes scope. Takes Idempotency-Key.

Body

FieldTypeNotes
serviceIdstring (uuid)
serviceIdsarray of string (uuid)up to 10 items
selectionsobject
addonsarray of stringup to 50 items
customerIdstring (uuid)
customerobject
notesstringup to 2000 characters
discountobject
recurringFrequency"weekly" | "biweekly" | "monthly"
checkInstring
checkOutstring
datestring
hoursinteger1 to 24
sendboolean
messagestringup to 4000 characters

Answers

  • 201 The quote.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    statusstringRequired.
    serviceIdstring or nullRequired.
    serviceNamestring or nullRequired.
    lineItemsarray of objectRequired.
    subtotalnumberRequired.
    discountnumberRequired.
    totalnumberRequired.
    customerobject or nullRequired.
    notesstring or nullRequired.
    checkInstring or nullRequired.
    checkOutstring or nullRequired.
    datestring or nullRequired.
    hoursnumber or nullRequired.
    validUntilstring or nullRequired.
    sentAtstring or nullRequired.
    bookingIdstring or nullRequired.
    channelstring or nullRequired.
    abandonedbooleanRequired.
    quoteUrlstringRequired.
    createdAtstringRequired.
    updatedAtstringRequired.
  • 400 invalid_request, customer_email_required, idempotency_key_invalid, business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 404 service_not_found, customer_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/account/quotes/{id}/send

Email a quote to its customer

Marks it sent and emails it, as "Send" does in the dashboard. Sending again sends it again.

Needs: The business’s API key, with the write:quotes scope. Takes Idempotency-Key.

Parameters

FieldTypeNotes
idstring (uuid)Required. In the path. The quote’s id.

Body (may be left out)

FieldTypeNotes
messagestringup to 4000 characters

Answers

  • 200 The quote, now sent.
    Fields of data
    FieldTypeNotes
    idstringRequired.
    statusstringRequired.
    serviceIdstring or nullRequired.
    serviceNamestring or nullRequired.
    lineItemsarray of objectRequired.
    subtotalnumberRequired.
    discountnumberRequired.
    totalnumberRequired.
    customerobject or nullRequired.
    notesstring or nullRequired.
    checkInstring or nullRequired.
    checkOutstring or nullRequired.
    datestring or nullRequired.
    hoursnumber or nullRequired.
    validUntilstring or nullRequired.
    sentAtstring or nullRequired.
    bookingIdstring or nullRequired.
    channelstring or nullRequired.
    abandonedbooleanRequired.
    quoteUrlstringRequired.
    createdAtstringRequired.
    updatedAtstringRequired.
  • 400 invalid_request, customer_email_required, idempotency_key_invalid, business_required
  • 401 api_key_required, api_key_invalid
  • 403 api_keys_off, api_access_not_in_plan, business_unavailable, partner_suspended, partner_wrong_business, partner_access_removed, scope_missing
  • 404 quote_not_found
  • 409 quote_already_booked
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off

Partner

For organisations that set businesses up for other people. A partner’s API key is required.

get/partner

The partner this key belongs to

Its name, how many businesses it has and how many it may have. The call to check a partner key with.

Needs: A partner’s API key.

Answers

  • 200 The partner.
    Fields of data
    FieldTypeNotes
    partnerobjectRequired.
    keyobjectRequired.
  • 401 api_key_required, api_key_invalid
  • 403 partners_off, partner_key_required, partner_suspended
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/partner/businesses

The businesses this partner has made

The newest first, each with whether its real owner has taken it over (claimed).

Needs: A partner’s API key.

Answers

  • 200 The businesses.
    Fields of data
    FieldTypeNotes
    businessesarray of objectRequired.
  • 401 api_key_required, api_key_invalid
  • 403 partners_off, partner_key_required, partner_suspended
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/partner/businesses

Make a business

An ordinary Free business with opening hours and the services sent (or the industry’s usual ones with starterServices). The partner’s account owns it until its real owner takes it over; nobody is emailed, and payments stay off until the owner sets them up. From then on this key can quote, book and read for it through the other operations.

Needs: A partner’s API key. Takes Idempotency-Key.

Body

FieldTypeNotes
namestringRequired. up to 255 characters
slugstringRequired. up to 100 characters
verticalstringup to 100 characters
emailstring (email)up to 255 characters
phonestringup to 50 characters
timezonestringRequired.
currencystringRequired. up to 3 characters
countrystring
localestringup to 35 characters
hoursarray of objectup to 7 items
servicesarray of objectup to 50 items
starterServicesboolean

Answers

  • 201 The business.
    Fields of data
    FieldTypeNotes
    businessobjectRequired.
  • 400 invalid_request, vertical_unknown, idempotency_key_invalid
  • 401 api_key_required, api_key_invalid
  • 403 partners_off, partner_key_required, partner_suspended
  • 409 slug_taken, business_limit_reached
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
get/partner/businesses/{slug}

One of this partner’s businesses

A business another partner made, or nobody did, is not found.

Needs: A partner’s API key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.

Answers

  • 200 The business.
    Fields of data
    FieldTypeNotes
    businessobjectRequired.
  • 401 api_key_required, api_key_invalid
  • 403 partners_off, partner_key_required, partner_suspended
  • 404 business_not_found
  • 429 rate_limited
  • 500 internal_error
  • 503 agent_platform_off
post/partner/businesses/{slug}/invite

Invite the real owner to take a business over

Emails that address one link, good for 14 days; sending again replaces it. When the owner accepts, the business is theirs and the partner keeps a seat the owner can remove. Three invitations a day for a business.

Needs: A partner’s API key.

Parameters

FieldTypeNotes
slugstringRequired. In the path. The business, as in its booking page address.

Body

FieldTypeNotes
emailstring (email)Required. up to 255 characters
namestringup to 255 characters

Answers

  • 201 The invitation was emailed.
    Fields of data
    FieldTypeNotes
    invitedobjectRequired.
  • 400 invalid_request
  • 401 api_key_required, api_key_invalid
  • 403 partners_off, partner_key_required, partner_suspended
  • 404 business_not_found
  • 409 already_claimed, business_closed
  • 429 invite_limit_reached, rate_limited
  • 500 internal_error
  • 502 email_not_sent
  • 503 agent_platform_off