Bookio
API docs by Redocly

Bookio Services Public API (1.1.0)

Download OpenAPI specification:

Bookio Support: [email protected] URL: https://www.bookio.com License: Proprietary

Authentication

Token based authentication. Access to bookio API with specific channel assigned to the token.

Bearer

Provided secret API token must be sent in Authorization request header:

    Authorization: Bearer <token>
Security Scheme Type: API Key
Header parameter name: Authorization

API Key

Api keys are generated in the tenant administration. Every key is issued with the READ policy, granting read-only access to the endpoints in this document. Write access is a work in progress. A key is also bound to the facilities it may read. Passing a facilityId the key does not cover fails with error code 20.

Rate limiting

Requests are metered per key. Every response carries a correlation id in X-Request-Id, and a successful one reports the remaining budget in X-API-Rate-Remaining. When the budget is exhausted the API answers 429 with a Retry-After header (seconds). Availability endpoints are heavier and consume 2 tokens per request instead of 1.

Error codes

A failed request answers with success: false plus a machine readable errorCode and errorType. HTTP 200 is only ever returned for a successful request, so a 200 body carries data and never carries errorCode or errors.

ErrorCode errorType HTTP Description
10 validation_error 400 Generic validation error, errors field will give more information
12 validation_error_no_resource 400 Resource not found
20 invalid_token 400 / 401 Invalid token or missing access rights. 401 when the Authorization header itself is missing or unknown, 400 when the key does not cover the requested facility
50 conflict 409 Resource already exists. Retryable, carries a Retry-After header
403 forbidden 403 You don't have enough permissions to access this endpoint
422 entity_validation_error 422 Validation error
429 too_many_requests 429 Too many requests
666 server_error 500 Unspecified internal error, this will be reported to us and we will look into it shortly

Dates and times

Unless stated otherwise, datetimes are rendered as yyyy-MM-ddTHH:mm:ss in the facility's local timezone and carry no UTC offset. Plain dates use yyyy-MM-dd, times of day HH:mm.

Language mutations

Every request accepts parameter lang. Example: /api/v1/some-endpoint?lang=sk or /api/v1/some-endpoint?someParam=1&lang=en. Controls the language of texts. Unsupported locale will fallback to "en".

Reservations

Listing of service reservations.

List of reservations

Returns a list of service reservations by filter, newest first.

Authorizations:
Bearer
query Parameters
facilityId
required
integer <int64> (Id)
Example: facilityId=123

Id of the facility. Must be covered by your api key.

email
string

Exact email of the reservee.

from
string <date> (Date)
Example: from=2026-08-06

Only reservations starting on or after this date.

to
string <date> (Date)
Example: to=2026-08-06

Only reservations ending on or before the end of this date.

offset
integer >= 0
Default: 0
Example: offset=50

Determines the offset within pagination.

limit
integer [ 0 .. 100 ]
Default: 100
Example: limit=50

Limits the result set.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Course Reservations

Listing of course reservations.

List of course reservations

Returns a list of course reservations by filter, newest first.

Authorizations:
Bearer
query Parameters
facilityId
required
integer <int64> (Id)
Example: facilityId=123

Id of the facility. Must be covered by your api key.

email
string

Exact email of the reservee.

offset
integer >= 0
Default: 0
Example: offset=50

Determines the offset within pagination.

limit
integer [ 0 .. 100 ]
Default: 25
Example: limit=50

Limits the result set.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Blocked Times

Listing of blocked (unavailable) time ranges of workers.

List of blocked times

Returns the blocked (unavailable) time ranges of the facility's workers, newest first.

A blocked time either covers whole days (allDay: true, no timeFrom/timeTo of its own — the facility's schedule bounds are reported instead) or a time window of each covered day. The restriction field says how the range repeats.

Authorizations:
Bearer
query Parameters
facilityId
required
integer <int64> (Id)
Example: facilityId=123

Id of the facility. Must be covered by your api key.

dateFrom
string <date> (Date)
Example: dateFrom=2026-08-06

Only blocked times starting on or after this date.

dateTo
string <date> (Date)
Example: dateTo=2026-08-06

Only blocked times ending on or before this date.

offset
integer >= 0
Default: 0
Example: offset=50

Determines the offset within pagination.

limit
integer [ 0 .. 100 ]
Default: 25
Example: limit=50

Limits the result set.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Availability

Bookable days, arrival times, course terms and free capacities — the same data the booking widget uses. These endpoints consume 2 rate limit tokens per request.

Bookable days

Days of the requested month that still have at least one bookable slot, starting from the requested date. Days before the service's earliest bookable time are never returned.

Costs 2 rate limit tokens.

Authorizations:
Bearer
query Parameters
facilityId
required
integer <int64> (Id)
Example: facilityId=123

Id of the facility. Must be covered by your api key.

serviceId
required
integer <int64> (Id)
Example: serviceId=123

Id of the service. Must belong to facilityId and be enabled.

date
required
string <date> (Date)
Example: date=2026-08-06

Any date of the month to scan. The scan starts at this date and runs to the end of its month.

workerIds
string
Example: workerIds=12,15

Comma separated worker ids to restrict the answer to. Ids not assigned to the service are dropped; if none remain the request fails with error code 10.

addonIds
string
Example: addonIds=3,7

Comma separated addon ids to include in the requested slot length.

count
integer >= 1
Example: count=2

Number of items to book at once, for item-based services.

participantsCount
integer >= 1
Example: participantsCount=3

Number of participants, for entry (room) services.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Bookable arrival times

Bookable arrival times of a single day. Returns an empty times array when the day is fully booked or entirely before the service's earliest bookable time.

Costs 2 rate limit tokens.

Authorizations:
Bearer
query Parameters
facilityId
required
integer <int64> (Id)
Example: facilityId=123

Id of the facility. Must be covered by your api key.

serviceId
required
integer <int64> (Id)
Example: serviceId=123

Id of the service. Must belong to facilityId and be enabled.

date
required
string <date> (Date)
Example: date=2026-08-06

Day to list arrival times for.

workerIds
string
Example: workerIds=12,15

Comma separated worker ids to restrict the answer to. Ids not assigned to the service are dropped; if none remain the request fails with error code 10.

addonIds
string
Example: addonIds=3,7

Comma separated addon ids to include in the requested slot length.

count
integer >= 1
Example: count=2

Number of items to book at once, for item-based services.

participantsCount
integer >= 1
Example: participantsCount=3

Number of participants, for entry (room) services.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Course terms

Currently offered terms of a course together with their free capacity.

Costs 2 rate limit tokens.

Authorizations:
Bearer
query Parameters
facilityId
required
integer <int64> (Id)
Example: facilityId=123

Id of the facility. Must be covered by your api key.

courseId
required
integer <int64> (Id)
Example: courseId=123

Id of the course.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Free capacity of entry services

Free capacity of the items (rooms) of an entry service at a given moment. Only available for services of type BELONGS_TO_ROOM; other service types are rejected with error code 10.

Costs 2 rate limit tokens.

Authorizations:
Bearer
query Parameters
facilityId
required
integer <int64> (Id)
Example: facilityId=123

Id of the facility. Must be covered by your api key.

serviceId
required
integer <int64> (Id)
Example: serviceId=123

Id of the service. Must belong to facilityId and be enabled.

start
required
string (LocalDateTime) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$
Example: start=2026-08-06T12:00:00

Moment to check, in facility local time.

itemId
integer <int64> (Id)
Example: itemId=123

Restrict the answer to a single item. Must belong to the service.

duration
integer >= 1
Example: duration=90

Length of the intended stay in minutes. Defaults to the service duration.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Facility

Facility master data — info, workers, services, addons, courses and items.

Get facility info

Returns the master data of a facility, including its address, contact, billing details, opening hours and gift cards.

Authorizations:
Bearer
path Parameters
facilityId
required
integer <int64> (Id)
Example: 123

Bookio facility id.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Get workers

Enabled workers and managers of the facility.

Authorizations:
Bearer
path Parameters
facilityId
required
integer <int64> (Id)
Example: 123

Bookio facility id.

Responses

Response samples

Content type
application/json
{}

Get services

Enabled, publicly bookable services of the facility. Services flagged as direct-reservation only are not returned. Capped at 200 rows.

Authorizations:
Bearer
path Parameters
facilityId
required
integer <int64> (Id)
Example: 123

Bookio facility id.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Get addons

Service addons of the facility, ordered by priority and name. Each addon lists the enabled services it can be added to.

Authorizations:
Bearer
path Parameters
facilityId
required
integer <int64> (Id)
Example: 123

Bookio facility id.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Get courses

Enabled, publicly bookable courses of the facility with their sub-courses and times.

Authorizations:
Bearer
path Parameters
facilityId
required
integer <int64> (Id)
Example: 123

Bookio facility id.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Get items

Enabled items (rooms/equipment) of the facility.

Authorizations:
Bearer
path Parameters
facilityId
required
integer <int64> (Id)
Example: 123

Bookio facility id.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Ratings

Facility ratings and their aggregated summary.

List of ratings

Ratings of the facility, newest first. A rating belongs either to a service reservation or to a course reservation — the type field says which, and the corresponding service or course object is filled in.

Censored ratings are included with their scores, but their note is returned as null and flagged by noteCensored.

Authorizations:
Bearer
query Parameters
facilityId
required
integer <int64> (Id)
Example: facilityId=123

Id of the facility. Must be covered by your api key.

from
string <date> (Date)
Example: from=2026-08-06

Only ratings added on or after this date.

to
string <date> (Date)
Example: to=2026-08-06

Only ratings added on or before this date.

serviceId
integer <int64> (Id)
Example: serviceId=123

Only ratings of reservations of this service.

courseId
integer <int64> (Id)
Example: courseId=123

Only ratings of reservations of this course.

hasNote
boolean

Filter to ratings that do (true) or do not (false) carry a written note.

lang
string (Locale)
Example: lang=sk

Language of the returned service/course names and category labels. Falls back to the facility language.

offset
integer >= 0
Default: 0
Example: offset=50

Determines the offset within pagination.

limit
integer [ 0 .. 100 ]
Default: 25
Example: limit=50

Limits the result set.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Aggregated rating

The aggregated rating of the facility — the same cached figures the booking widget shows.

Authorizations:
Bearer
query Parameters
facilityId
required
integer <int64> (Id)
Example: facilityId=123

Id of the facility. Must be covered by your api key.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Loyalty System

Integration with external loyalty systems.

Check customer

Checks whether a customer is registered in the facility's loyalty system and returns their next upcoming booking.

Requires the loyalty integration to be enabled for your key and for the facility.

Authorizations:
Bearer
path Parameters
loyaltySystem
required
string

Loyalty system the facility is integrated with. Case insensitive.

query Parameters
email
required
string

Email of the customer.

bookioId
required
integer <int64> (Id)
Example: bookioId=123

Bookio facility id.

externalId
required
string
Example: externalId=21312

Business id of the facility in the external loyalty system. Must match the facility's configured integration.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Next booking

Returns the customer's nearest upcoming booking. Fails with error code 12 when the customer is not in the loyalty system.

Requires the loyalty integration to be enabled for your key and for the facility.

Authorizations:
Bearer
path Parameters
loyaltySystem
required
string

Loyalty system the facility is integrated with. Case insensitive.

query Parameters
email
required
string

Email of the customer.

bookioId
required
integer <int64> (Id)
Example: bookioId=123

Bookio facility id.

externalId
required
string
Example: externalId=21312

Business id of the facility in the external loyalty system. Must match the facility's configured integration.

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Register customer

Registers a customer in the facility's loyalty system.

When the customer already has a card the response carries error code 50 and still returns the existing card in data.

Requires the loyalty integration to be enabled for your key and for the facility.

Authorizations:
Bearer
path Parameters
loyaltySystem
required
string

Loyalty system the facility is integrated with. Case insensitive.

Request Body schema: application/json
required
bookioId
required
integer <int64>

Bookio facility id.

externalId
required
string

Business id of the facility in the external loyalty system.

externalCardId
string

Loyalty card id from the external system.

email
required
string

Email of the customer.

name
string

First name of the customer.

surname
string

Surname of the customer.

phone
string

Phone of the customer.

Responses

Request samples

Content type
application/json
{
  • "bookioId": 123,
  • "externalId": "141512",
  • "externalCardId": "08ab382e-1162-4d35-8c5b-ab1064b1afc7",
  • "email": "[email protected]",
  • "name": "John",
  • "surname": "Audrey",
  • "phone": "+421944888777"
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

WebHooks

Webhook is setup to point to one API url. Operations are distinguished by type field. We are using only POST http request.

Based on the `type` field the structure of the Json will change.
Webhooks are retried a limited number of times (timeout, your api is down, etc ...).

Further you can find structures of the webhooks.

Both service reservations and course reservations are delivered through the same webhooks — a service reservation carries a service object, a course reservation carries a course object instead.

If the partner is configured with an auth type, the configured value is sent in the Authorization request header.

Create reservation Webhook

Sent when a reservation is created.

The data object is a service reservation (carries service) or a course reservation (carries course).

Request Body schema: application/json
required
type
string
Value: "create_reservation"

Unique webhook type. This will tell you what structure to parse.

Type: create_reservation

WebhookServiceReservation (object) or WebhookCourseReservation (object)

Main data holder.

Responses

Request samples

Content type
application/json
{
  • "type": "create_reservation",
  • "data": {
    }
}

Edit reservation Webhook

Sent when a reservation is modified.

The data object is a service reservation (carries service) or a course reservation (carries course).

Request Body schema: application/json
required
type
string
Value: "modify_reservation"

Unique webhook type. This will tell you what structure to parse.

Type: modify_reservation

WebhookServiceReservation (object) or WebhookCourseReservation (object)

Main data holder.

Responses

Request samples

Content type
application/json
{
  • "type": "modify_reservation",
  • "data": {
    }
}

Cancel reservation Webhook

Sent when a reservation is cancelled. Fired for both service and course reservations — the payload is the same in either case.

Request Body schema: application/json
required
type
string
Value: "cancel_reservation"

Unique webhook type. This will tell you what structure to parse.

Type: cancel_reservation

object (WebhookCancelledReservation)

Payload of a cancellation webhook, for both service and course reservations.

Responses

Request samples

Content type
application/json
{
  • "type": "cancel_reservation",
  • "data": {
    }
}