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.

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.

int

The ID of the location 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'.

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 so that is considered fully paid.
Allowed values:
true,false

If set

object

The user to which the booking has been made.

If set

string

Notes about the booking.

If set

bool

Tells if the booking has been marked as confirmed.
Allowed values:
true,false

If set

string

Campaign code reference if available and AD tracking is enabled.

int

User interface where booking is created. (1 = admin, 2 = www)

datetime

The date and time when the booking was created.

If set

datetime

The date and time when the booking was modified. Included only if the booking has been modified.

If set

int

Booking start offset time in minutes.

If set

int

Booking end offset time in minutes.

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

Lists bookings for a specific date or a date range according to the given arguments. The default is the current date.

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. If this and from_date are omitted, the current date is used as default.

Optional

date

List bookings from this date.

Optional

date

List bookings to this date.

Optional

datetime

Include only bookings that have changed since this date and time. Includes both creates and modifications.

Optional

bool

If true only confirmed bookings are included.
Allowed values:
true,false

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.

List IDs of deleted bookings

Lists IDs of bookings that have been deleted on a specific date or during a date range. The default is the current date.

Arguments

Optional

date

List IDs of bookings deleted this date. If this and from_date are omitted, the current date is used as default.

Optional

date

List IDs of bookings deleted after this date.

Optional

date

List IDs of bookings deleted before 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

Create a service booking

Arguments

Required

int

Booking location ID.

Required

int

Booking service ID.

Required

date

Booking date.

Required

time

Booking start time.

Required

int list

IDs of resources assigned to the booking. Set to 'null' to unset.

Optional

int list

IDs of selected extra services. Set to 'null' to unset.

Optional

int list

IDs of selected service alternatives. Set to 'null' to unset.

Required

int

Customers user ID.

Optional

object

Extra info for booking.

Create a course booking

Arguments

Required

int

ID of the course.

Required

int

Customers user ID.

Optional

object

Extra info for booking.

Create a resource booking

Arguments

Required

int

Booking location ID.

Required

date

Booking date.

Required

time

Booking start time.

Required

time

Booking duration.

Required

int list

IDs of resources assigned to the booking.

Required

int

Customers user ID.

Optional

object

Extra information for the booking.

Delete a booking

Arguments

Required

int

ID of the object.

Confirm a booking

Arguments

Required

int

ID of the object.

Unconfirm a booking

Arguments

Required

int

ID of the object.

The payment object

Attributes

string

String is 'payment'.

int

ID of the payment.

string

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

float

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

float

Tax percentage.
Range: 0 - 100

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
Default: cash

Required

float

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

Required

float

Tax percentage.
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

User type.
Allowed values:
normal,temporary,company

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 - 2026

If set

string

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

Get a user object

Arguments

Required

int

ID of the user.

Returns

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

List user objects

Lists registered users, optionally limiting to those belonging to a specific user group. Does not include temporary users

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

Optional

int

Include only users belonging to the group with the given ID.

Returns

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

Create a user object

Arguments

Optional

string

User type.
Allowed values:
normal,temporary,company
Default: normal

Required

string

The user's first name.

Required

string

The user's last name.

Optional

email

The user's email address

Optional

phone

The user's phone number.

Optional

string

The user's street address.

Optional

zip_code

The user's address ZIP code.

Optional

string

The user's city.

Optional

int

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

Optional

string

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

Optional

int

Will digitalbooker send account information to user

Optional

string

Password set for the user.

Optional

int

Allow transactional emails
Default: 1

Optional

int

Allow marketing emails
Default: 0

Optional

int

Allow transactional sms
Default: 1

Optional

int

Allow marketing sms
Default: 1

Returns

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

Edit a user object

Arguments

Required

string

The user's first name.

Required

string

The user's last name.

Optional

email

The user's email address

Optional

phone

The user's phone number.

Optional

string

The user's street address.

Optional

zip_code

The user's address ZIP code.

Optional

string

The user's city.

Optional

int

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

Optional

string

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

Delete a user object

Arguments

Required

int

ID of the user.

Returns

Returns id of the deleted user object on success, or an error on failure.

The user group object

Attributes

string

String is 'user_group'.

int

Id of the user group.

string

Name of the user group (localized).

Get a user group object

Arguments

Required

int

ID of the object.

List user group objects

List groups a user belongs to

Arguments

Required

int

ID of the user.

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

float

Latitude geolocation

If set

float

Longitude geolocation

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

If set

string

External ID of the location if set to be included.

Get a location object

Arguments

Required

int

ID of the location.

Optional

bool

Fetches external IDs and includes them in the result if set to true.
Allowed values:
true,false

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

Optional

bool

Fetches external IDs and includes them in the result if set to true.
Allowed values:
true,false

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).

int

The ID of the category this resource belongs to.

If set

string

Description of the resource (localized).

If set

object

User account connected to the resource.

If set

bool

Tells if the resource accepts time bookings, ie. is directly bookable through the public interface.
Allowed values:
true,false

If set

string

External ID of the resource if set to be included.

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 in the category with this ID.

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.

The resource category object

Attributes

string

String is 'resource_category'.

int

Id of the category.

string

Name of the category (localized).

string

The resource type od this category. 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

Get a resource category

Arguments

Required

int

ID of the resource category.

List resource categories

Arguments

Optional

string

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

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

Workers

Methods to manage data related to workers. Workers are a type of resources so these are methods that are specific to workers only. The other methods are found in the resources section.

List a worker's work hours

Lists the work hours for the resource for all its locations.

Arguments

Required

int

ID of the resource.

Optional

date

Date to get work hours for. If this and from_date are omitted, the current date is used as default.

Optional

date

List work hours from this date.

Optional

date

List work hours to this date.

Returns

Returns worker's work hours by date and location, plus has_more to indicate if more objects exists, or an error on failure.

List work hours for location

Lists the work hours for the resource in the given location.

Arguments

Required

int

ID of the resource.

Required

int

The ID of the location the work hours of which should be fetched.

Optional

date

Date to get work hours for. If this and from_date are omitted, the current date is used as default.

Optional

date

List work hours from this date.

Optional

date

List work hours to this date.

Returns

Returns worker's work hours by date, plus has_more to indicate if more objects exists, or an error on failure.

Add work hours

Defines work hours for a specific resource. Removes work hours for defined date before add.

Arguments

Required

int

ID of the resource.

Required

int

The ID of the location to which the work hours should be defined.

Optional

object list

A list of dates with the corresponding work hours.

Remove work hours

Removes the work hours matching the given parameters from the specific resource.

Arguments

Required

int

ID of the resource.

Required

int

List resources for the location with this ID.

Required

date

The date of the work hours.

Services

The service object

Attributes

string

String is 'service'.

int

Service ID.

string

The name of the service.

If set

string

The description of the service.

int

Service category ID.

Get a service object

Arguments

Required

int

ID of the object.

Returns

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

List service 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 service objects, plus has_more to indicate if more objects exists, or an error on failure.

The service category object

Attributes

string

String is 'category'.

int

Id of the category.

string

Name of the category (localized).

Get a service category object

Arguments

Required

int

ID of the object.

List service category 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

Class types

The class type category object

Attributes

string

String is 'category'.

int

Id of the category.

string

Name of the category (localized).

Get a class category object

Arguments

Required

int

ID of the category.

List class category 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

The class type object

Attributes

string

String is 'class_type'.

int

Class ID.

string

The title of the class.

If set

string

The description of the class.

int

Class category ID.

Get a class type object

Arguments

Required

int

ID of the object.

Returns

Returns class type object on success, or an error on failure.

List class type 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 class type 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

bool

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

If set

float

Latitude geolocation

If set

float

Longitude geolocation

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.

int

Number of upcoming days that the booking view allows.

If set

object

Specifies the worker selection options if available.

If set

string

Name to be used in the worker selector.

If set

time list

Duration alternatives available for the resource.

If set

int

Max amount of resource time bookings that can be made at once.

bool

Tells if the booking view has extra info specified for bookings.
Allowed values:
true,false

bool

Tells if the booking view has week browser enabled.
Allowed values:
true,false

If set

bool

Tells if the booking view is a one-service view (no selectors).
Allowed values:
true,false

If set

object

Specifies the user-specific booking limit.

If set

bool

Tells if thumbnails of worker images are to be displayed in worker selectors.
Allowed values:
true,false

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 category.

string

Name of the 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

Optional

bool

If set and, there are no available times available for the given week, the date for the next available times is returned.
Allowed values:
true,false
Default: false

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).

int

ID of the category of the class.

int

ID of the location where the class is held.

date

Date of the class.

time

Start time of the class.

time

End time of the class.

If set

int

Current number of bookings. Set depending on system settings.

If set

int

Min number of bookings for the class. Set depending on system settings.

If set

int

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

If set

float

Class price (including tax).

If set

float

Class tax.

If set

object

Description obejct 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

int

Amount of bookings in queue, set if the class has a queue

If set

int

Show places available. Set depending on system settings.

If set

string

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

If set

object

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

If set

string

Class color hex value.

The class category object

Attributes

string

String is 'class_category'.

int

Id of the category.

string

Name of the 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,all
Default: week

Optional

int list

IDs of class categories to filter by.

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

Optional

bool

If set and, there are no available times available for the given week, the date for the next available times is returned.
Allowed values:
true,false
Default: false

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.

If set

int list

List of IDs of resources that get blocked by this resource if the feature is enabled.

List bookable resources

Arguments

Required

string

URL identifier (url_text) of the location.

Required

string

URL identifier (url_text) of the view.

Returns

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

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)