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
| Field | Type | Notes |
|---|
| business | object | Required. |
| key | object | Required. |
- 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
| Field | Type | Notes |
|---|
| status | "pending_payment" | "pending_confirmation" | "confirmed" | "in_progress" | "completed" | "cancelled" | "no_show" | In the query. Only bookings with this status. |
| from | string | In the query. Bookings that start on or after this day, in the business’s zone. |
| to | string | In the query. Bookings that start on or before this day. |
| createdSince | string (date-time) | In the query. Bookings made at or after this instant. |
| customerId | string (uuid) | In the query. One customer’s bookings. |
| limit | integer | In the query. How many, 1 to 50. 1 to 50 |
| cursor | string | In the query. nextCursor of the page before. |
Answers
- 200 A page of bookings.
Fields of data
| Field | Type | Notes |
|---|
| timezone | string | Required. |
| currency | string | Required. |
| bookings | array of object | Required. |
| nextCursor | string or null | Required. |
- 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
| Field | Type | Notes |
|---|
| id | string (uuid) | Required. In the path. The booking’s id. |
Answers
- 200 The booking.
Fields of data
| Field | Type | Notes |
|---|
| id | string | Required. |
| status | string | Required. |
| paymentStatus | string | Required. |
| serviceId | string or null | Required. |
| serviceName | string or null | Required. |
| start | string | Required. |
| end | string | Required. |
| durationMinutes | number | Required. |
| nights | number or null | Required. |
| total | number | Required. |
| deposit | number | Required. |
| balance | number | Required. |
| recurringFrequency | string or null | Required. |
| notes | string or null | Required. |
| customer | object | Required. |
| channel | string or null | Required. |
| agentName | string or null | Required. |
| customerUrl | string or null | Required. |
| createdAt | string | Required. |
| updatedAt | string | Required. |
- 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
| Field | Type | Notes |
|---|
| email | string | In the query. The customer with exactly this address. |
| q | string | In the query. Customers whose name or email contains this. |
| limit | integer | In the query. How many, 1 to 50. 1 to 50 |
| cursor | string | In the query. nextCursor of the page before. |
Answers
- 200 A page of customers.
Fields of data
| Field | Type | Notes |
|---|
| currency | string | Required. |
| customers | array of object | Required. |
| nextCursor | string or null | Required. |
- 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
| Field | Type | Notes |
|---|
| id | string (uuid) | Required. In the path. The booking’s id. |
Body
| Field | Type | Notes |
|---|
| action | "confirm" | "decline" | "start" | "complete" | "cancel" | "no_show" | Required. |
| reason | string | up to 500 characters |
Answers
- 200 The booking as it now is.
Fields of data
| Field | Type | Notes |
|---|
| id | string | Required. |
| status | string | Required. |
| paymentStatus | string | Required. |
| serviceId | string or null | Required. |
| serviceName | string or null | Required. |
| start | string | Required. |
| end | string | Required. |
| durationMinutes | number | Required. |
| nights | number or null | Required. |
| total | number | Required. |
| deposit | number | Required. |
| balance | number | Required. |
| recurringFrequency | string or null | Required. |
| notes | string or null | Required. |
| customer | object | Required. |
| channel | string or null | Required. |
| agentName | string or null | Required. |
| customerUrl | string or null | Required. |
| createdAt | string | Required. |
| updatedAt | string | Required. |
- 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
| Field | Type | Notes |
|---|
| id | string (uuid) | Required. In the path. The booking’s id. |
Body
| Field | Type | Notes |
|---|
| slotId | string | up to 1024 characters |
| start | string (date-time) | |
| confirmTotal | number | 0 or more |
Answers
- 200 The booking as it now is.
Fields of data
| Field | Type | Notes |
|---|
| id | string | Required. |
| status | string | Required. |
| paymentStatus | string | Required. |
| serviceId | string or null | Required. |
| serviceName | string or null | Required. |
| start | string | Required. |
| end | string | Required. |
| durationMinutes | number | Required. |
| nights | number or null | Required. |
| total | number | Required. |
| deposit | number | Required. |
| balance | number | Required. |
| recurringFrequency | string or null | Required. |
| notes | string or null | Required. |
| customer | object | Required. |
| channel | string or null | Required. |
| agentName | string or null | Required. |
| customerUrl | string or null | Required. |
| createdAt | string | Required. |
| updatedAt | string | Required. |
- 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
| Field | Type | Notes |
|---|
| webhooks | array of object | Required. |
| events | array of string | Required. |
- 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
| Field | Type | Notes |
|---|
| url | string | Required. up to 2000 characters |
| events | array of string | Required. |
| description | string | up to 200 characters |
Answers
- 201 Added.
secret is not shown again.Fields of data
| Field | Type | Notes |
|---|
| id | string | Required. |
| url | string | Required. |
| description | string or null | Required. |
| events | array of string | Required. |
| active | boolean | Required. |
| createdAt | string | Required. |
| secret | string | Required. |
- 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
| Field | Type | Notes |
|---|
| id | string (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
| Field | Type | Notes |
|---|
| id | string (uuid) | Required. In the path. The customer’s id. |
Answers
- 200 The customer.
Fields of data
| Field | Type | Notes |
|---|
| id | string | Required. |
| name | string | Required. |
| email | string or null | Required. |
| phone | string or null | Required. |
| tags | array of string | Required. |
| bookingCount | integer | Required. |
| lifetimeValue | number | Required. |
| firstBookedAt | string or null | Required. |
| lastBookedAt | string or null | Required. |
- 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
| Field | Type | Notes |
|---|
| name | string | Required. up to 255 characters |
| email | string (email) | up to 255 characters |
| phone | string | up to 50 characters |
| notes | string | up to 5000 characters |
| tags | array of string | up to 20 items |
Answers
- 200 The business already had them.
Fields of data
| Field | Type | Notes |
|---|
| created | boolean | Required. |
| customer | object | Required. |
- 201 Added.
Fields of data
| Field | Type | Notes |
|---|
| created | boolean | Required. |
| customer | object | Required. |
- 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
| Field | Type | Notes |
|---|
| status | "pending" | "sent" | "accepted" | "expired" | "converted" | "declined" | In the query. Only quotes with this status. |
| createdSince | string (date-time) | In the query. Quotes made at or after this instant. |
| customerId | string (uuid) | In the query. One customer’s quotes. |
| limit | integer | In the query. How many, 1 to 50. 1 to 50 |
| cursor | string | In the query. nextCursor of the page before. |
Answers
- 200 A page of quotes.
Fields of data
| Field | Type | Notes |
|---|
| timezone | string | Required. |
| currency | string | Required. |
| quotes | array of object | Required. |
| nextCursor | string or null | Required. |
- 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
| Field | Type | Notes |
|---|
| id | string (uuid) | Required. In the path. The quote’s id. |
Answers
- 200 The quote.
Fields of data
| Field | Type | Notes |
|---|
| id | string | Required. |
| status | string | Required. |
| serviceId | string or null | Required. |
| serviceName | string or null | Required. |
| lineItems | array of object | Required. |
| subtotal | number | Required. |
| discount | number | Required. |
| total | number | Required. |
| customer | object or null | Required. |
| notes | string or null | Required. |
| checkIn | string or null | Required. |
| checkOut | string or null | Required. |
| date | string or null | Required. |
| hours | number or null | Required. |
| validUntil | string or null | Required. |
| sentAt | string or null | Required. |
| bookingId | string or null | Required. |
| channel | string or null | Required. |
| abandoned | boolean | Required. |
| quoteUrl | string | Required. |
| createdAt | string | Required. |
| updatedAt | string | Required. |
- 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
| Field | Type | Notes |
|---|
| serviceId | string (uuid) | |
| serviceIds | array of string (uuid) | up to 10 items |
| selections | object | |
| addons | array of string | up to 50 items |
| customerId | string (uuid) | |
| customer | object | |
| notes | string | up to 2000 characters |
| discount | object | |
| recurringFrequency | "weekly" | "biweekly" | "monthly" | |
| checkIn | string | |
| checkOut | string | |
| date | string | |
| hours | integer | 1 to 24 |
| send | boolean | |
| message | string | up to 4000 characters |
Answers
- 201 The quote.
Fields of data
| Field | Type | Notes |
|---|
| id | string | Required. |
| status | string | Required. |
| serviceId | string or null | Required. |
| serviceName | string or null | Required. |
| lineItems | array of object | Required. |
| subtotal | number | Required. |
| discount | number | Required. |
| total | number | Required. |
| customer | object or null | Required. |
| notes | string or null | Required. |
| checkIn | string or null | Required. |
| checkOut | string or null | Required. |
| date | string or null | Required. |
| hours | number or null | Required. |
| validUntil | string or null | Required. |
| sentAt | string or null | Required. |
| bookingId | string or null | Required. |
| channel | string or null | Required. |
| abandoned | boolean | Required. |
| quoteUrl | string | Required. |
| createdAt | string | Required. |
| updatedAt | string | Required. |
- 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
| Field | Type | Notes |
|---|
| id | string (uuid) | Required. In the path. The quote’s id. |
Body (may be left out)
| Field | Type | Notes |
|---|
| message | string | up to 4000 characters |
Answers
- 200 The quote, now sent.
Fields of data
| Field | Type | Notes |
|---|
| id | string | Required. |
| status | string | Required. |
| serviceId | string or null | Required. |
| serviceName | string or null | Required. |
| lineItems | array of object | Required. |
| subtotal | number | Required. |
| discount | number | Required. |
| total | number | Required. |
| customer | object or null | Required. |
| notes | string or null | Required. |
| checkIn | string or null | Required. |
| checkOut | string or null | Required. |
| date | string or null | Required. |
| hours | number or null | Required. |
| validUntil | string or null | Required. |
| sentAt | string or null | Required. |
| bookingId | string or null | Required. |
| channel | string or null | Required. |
| abandoned | boolean | Required. |
| quoteUrl | string | Required. |
| createdAt | string | Required. |
| updatedAt | string | Required. |
- 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