Description Examples

Introduction

The DigitalBooker API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. All responses from the API will be encoded as JSON.

Our API is divided into two main parts, the Public API and the Admin API. The DigitalBooker Public API can be used to access publicly available data, while the DigitalBooker Admin API allows fetching the system's internal data.

We support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret authentication credentials in any public website's client-side code).

Localization

DigitalBooker supports multiple languages. Just change the language identifier in the API endpoint URL to get the responses in your selected language. Please note that almost all localized strings in the system are user generated. If a localization is not provided by the system administrator, the API will fallback to any defined localization.

Authentication

Authentication is required by the DigitalBooker Admin API as it opens access to some of the system's internal information, like bookings. You authenticate to the Admin API through HTTP Basic Auth by providing one of your API keys in the request. Provide the ID of the API key as the username and its password as the password. Note that there may be key-specific privileges affecting which API methods can be used with the given API key.

Your API keys carry many privileges, so remember: Keep them secret, keep them safe!

In case you fear an API key has gone into wrong hands, just delete the key and generate a new one. Multiple API keys is allowed so you can for example have separate keys for each integration partner.

All API requests must be made over HTTPS. Note that all requests do NOT require autentication.

API keys can be taken into use through the DigitalBooker App Store.

Errors

DigitalBooker uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing.), and codes in the 5xx range indicate an error with the's servers.

Attributes

string

Error code

If set

string

Human readable error message.

If set

list

A list of errors, usually for which parameters were invalid, plus possible explanations.

Pagination

The APIs list methods are used to fetch mulitple objects of any given resource. All list objects share the same structure. DigitalBooker utilizes cursor based pagination.

Arguments

int

Number of objects being returned. Range 1 to 100.

int

A cursor to define from where in the list to start.

Response

string

Value is 'list'.

array

Array of response objects.

bool

Defines if there is more objects to fetch.

int

Holds the total count of the complete result set.

Bookings

Methods to fetch data about the bookings in your system.

The booking object

Attributes

string

String is 'booking'.

int

Booking ID.

string

Booking type.
Allowed values:
service,class,resource

string

The title of the booking.

date

The date of the booking.

time

Booking start time.

time

Booking end time.

If set

int

The service ID if the booking is of type 'service'.

If set

int

The class ID if the booking is of type 'class'.

int

The ID of the location of the booking.

If set

int list

The IDs of the resources of the booking.

If set

float

Booking price (including tax).

If set

float

Booking tax.

If set

bool

Tells if the booking has payments or not.
Allowed values:
true,false

If set

object

The user to which the booking has been made.

If set

string

Notes about the booking.

Get a booking object

Arguments

Required

int

ID of the booking.

Returns

Returns booking object on success, or an error on failure.

List booking objects

Arguments

Optional

int

List bookings for the location with this ID.

Optional

int list

List bookings with resources matching these IDs

Optional

date

List bookings for this date.

Optional

date

List bookings from this date.

Optional

date

List bookings to this date.

Optional

int

Number of objects being returned.
Range: 1 - 100
Default: 100

Optional

int

A cursor to define from where in the list to start.
Default: 0

Returns

Returns list of booking objects, plus has_more to indicate if more objects exists, or an error on failure.

Get a payment for a booking

Arguments

Required

int

ID of the booking.

Required

int

ID of the payment.

List payments for a booking

Arguments

Required

int

ID of the booking.

Add a payment to a booking

Arguments

Optional

string

Type of payment.
Allowed values:
cash,prepaid,other
Default: cash

Required

float

Amount of the payment including tax.
Range: 0 - 99999

Required

float

Tax.
Range: 0 - 100

Users

Methods to fetch data about users in the system.

Responses from other methods that include references to users doesn't typically fully expand the user data. These methods can then be used to fetch complete user data.

The user object

Attributes

string

String is 'user'.

int

The ID of the user.

string

The full name of the user.

email

The email address of the user.

If set

phone

The user's phone number.

string

Booking type.
Allowed values:
normal,temporary,group

If set

string

The user's street address.

If set

zip_code

The user's address ZIP code.

If set

string

The user's city.

If set

int

The user's birth year.
Range: 1900 - 2016

If set

string

The user's gender.
Allowed values:
female,male

Get a user object

Arguments

Required

int

ID of the user.

Returns

Returns user object on success, or an error on failure.

Locations

Methods to fetch data about locations. Compared to the corresponding methods in the Public API, the results here include more comprehensive data.

The location object

Attributes

string

String is 'location'.

int

Id of the location.

string

Name of the location (localized).

string

URL identifier of the location.

If set

string

Location address (localized).

If set

string

Location zip code.

If set

string

Location city (localized)

If set

string

Location country code

If set

string

Location phone number.

If set

bool

True if the location has business hours enabled.
Allowed values:
true,false

If set

bool

Tells if the location is available in the admin calendar.
Allowed values:
true,false

If set

bool

Tells if the location is publicly visible.
Allowed values:
true,false

If set

bool

True if the location is included in the menu on the public booking site.
Allowed values:
true,false

Get a location object

Arguments

Required

int

ID of the location.

Returns

Returns location object on success, or an error on failure.

List location objects

Arguments

Optional

int

Number of objects being returned.
Range: 1 - 100
Default: 100

Optional

int

A cursor to define from where in the list to start.
Default: 0

Returns

Returns list of location objects, plus has_more to indicate if more objects exists, or an error on failure.

Resources

Methods to fetch data about resources. Resources include both workers and physical resources such as rooms.

The resource object

Attributes

string

String is 'resource'.

int

Resource id.

string

Type of resource. Type 'resource' is usually a physical resource, e.g. a room. Resources of type 'worker' are humans, e.g. hair stylists, instructors etc.
Allowed values:
resource,worker

string

Name of the resource (localized).

If set

object

User account connected to the resource.

Get a resource object

Arguments

Required

int

ID of the resource.

Returns

Returns resource object on success, or an error on failure.

List resource objects

Arguments

Optional

string

List resources of the given type only.
Allowed values:
resource,worker

Optional

int

List resources for the location with this ID.

Optional

int

Number of objects being returned.
Range: 1 - 100
Default: 100

Optional

int

A cursor to define from where in the list to start.
Default: 0

Returns

Returns list of resource objects, plus has_more to indicate if more objects exists, or an error on failure.

Locations

The public methods are used to fetch data that should be visible for end users.

The location object

Attributes

string

String is 'location'.

int

Id of the location.

string

Name of the location (localized).

string

URL identifier of the location.

If set

string

Location address (localized).

If set

string

Location zip code.

If set

string

Location city (localized)

If set

string

Location country code

If set

string

Location phone number.

If set

object list

List of view objects that are available in the location.

Get a location object

Arguments

Required

string

URL identifier (url_text) of the location.

Optional

string list

Extend properties of the location object.
Allowed values:
views

Returns

Returns location object on success, or an error on failure.

List location objects

Returns

Returns list of location objects, plus has_more to indicate if more objects exists, or an error on failure.

Views

The view object

Attributes

string

String is 'view'.

int

Id of the view.

string

Type of the view.
Allowed values:
services,classes,time,time-list,courses

string

Name of the view (localized).

string

URL identifier of the view.

If set

object

Specifies the worker selection options if available.

Get a view object

Arguments

Required

string

URL identifier (url_text) of the location.

Required

string

URL identifier (url_text) of the view.

Returns

Returns view object on success, or an error on failure.

List view objects

Returns

Returns list of view objects, plus has_more to indicate if more objects exists, or an error on failure.

Services

The service object

Attributes

string

String is 'service'.

int

Id of the service.

string

Name of the service (localized).

If set

object

Description obejct of the service.

If set

bool

Tells whether the service has alternatives or not (E.g. Hair length, Gender etc). If true, the service will not have durations set.
Allowed values:
true,false

If set

object list

List of extra service objects available to the service.

If set

time list

Duration alternatives available for the service. If set, has_alternatives will not be set.

If set

bool

Tells if the service is a phone-only type of service.
Allowed values:
true,false

If set

int

How many extra services have to be selected in order to create a booking.

The service category object

Attributes

string

String is 'service_category'.

int

Id of the service category.

string

Name of the service category (localized).

If set

object list

Available services in the service category.

List service objects

Arguments

Required

string

URL identifier (url_text) of the location.

Required

string

URL identifier (url_text) of the view.

Returns

Returns list of service category objects, plus has_more to indicate if more objects exists, or an error on failure.

List service alternatives objects

Arguments

Required

string

URL identifier (url_text) of the location.

Required

string

URL identifier (url_text) of the view.

Required

int

Service id.

Optional

int list

Extra service ids.

Returns

Returns list of alternatives objects, plus has_more to indicate if more objects exists, or an error on failure.

List service resources

Arguments

Required

string

URL identifier (url_text) of the location.

Required

string

URL identifier (url_text) of the view.

Required

int

Service id.

Optional

int list

Extra service ids.

Optional

int list

Selected alternatives.

Optional

time

Duration of the service, if service has multiple durations.

Returns

Returns list of resource objects, plus has_more to indicate if more objects exists, or an error on failure.

List available times

Arguments

Required

string

URL identifier (url_text) of the location.

Required

string

URL identifier (url_text) of the view.

Required

int

Service id.

Optional

int

Id of the worker to perform the service. In not set, check all workers

Optional

int list

Extra service ids.

Optional

int list

Selected alternatives.

Optional

time

Duration of the service, if service has multiple durations.

Optional

date

Date to search for available times
Default: today

Optional

string

Range of dates
Allowed values:
day,week,next7
Default: week

Returns

Returns list of available times, plus has_more to indicate if more objects exists, or an error on failure.

Classes

The class object

Attributes

string

String is 'class'.

int

Id of the class.

string

Name of the class (localized).

If set

object

Description obejct of the class.

int

ID of the category of the class.

date

Date of the class.

time

Start time of the class.

time

End time of the class.

string

Class status.
Allowed values:
bookable,full,cancelled,not-bookable

If set

bool

True if the class has a queue, meaning booking can be made although its already full.
Allowed values:
true,false

If set

string

Direct booking url to class, set if status is 'bookable'.

If set

int

Current number of bookings. Set depending on system settings.

If set

int

Max number of bookings for the class. Set depending on systm settings.

If set

object

List of resource objects for the class. Set depending on systm settings.

If set

float

Class price (including tax).

If set

float

Class tax.

If set

string

Class color hex value.

The class category object

Attributes

string

String is 'class_category'.

int

Id of the class category.

string

Name of the class category (localized).

string list

Names of the class types in the category.

List available classes

Arguments

Required

string

Url_text of the location.

Required

string

URL identifier (url_text) of the view.

Optional

date

Date to search for available classes
Default: today

Optional

string

Range of dates.
Allowed values:
day,week,next7
Default: week

Optional

int list

IDs of class categories to filter by.

Returns

Returns list of class objects, plus has_more to indicate if more objects exists, or an error on failure.

Resources

The resource object

Attributes

string

String is 'resource'.

int

Resource id.

string

Type of resource. Type 'resource' is usually a physical resource, e.g. a room. Resources of type 'worker' are humans, e.g. hair stylists, instructors etc.
Allowed values:
resource,worker

string

Name of the resource (localized).

If set

object

Description object of the resource.

Other

The description object

Description objects consist of a text body, and a list of icon objects. The description objects can be part part services, alternatives or resources objects.

Attributes

string

String is 'description'.

If set

string

Description body (localized)

If set

object list

List of icon objects.

The icon object

Attributes

string

String is 'icon'.

string

Icon identifier. Allowed values are all the icons in the Font Awesome icon set.

string

Icon label (localized)