Introduction

Welcome to the bookingtime API!

The bookingtime API is RESTful. It accepts and returns JSON in the HTTP body. URL´s are predictable and the usual CRUD operations are extended with Link/Unlink methods. Responses always have a message and a body, either one of them can be empty. The message contains an explanatory text and the corresponding parameter.

App or Module API?

There are two APIs you can choose from depending on your use case. The App API provides all the actions you need to connect your software with bookingtime. If you only want to build your own interface for the actual booking of appointments, please use the Module API.

Javascript SDK

The bookingtime javascript SDK consists of several libraries to get your project started. The capabilities of this SDK include authentication, rich Typescript interfaces for each core entity with mock objects, custom React hooks to easily fetch and store data using Redux, ready-to-use validation schemes to ensure data integrity of forms, and much more.

Currently, these libraries are not publicly available.

Authentication

The bookingtime APIs use the OAuth 2.0 protocol for authentication. This supports common OAuth 2.0 scenarios for single page applications (via Authorization Code Flow) and machine-to-machine communication (via Client Credentials Flow). Unauthenticated requests are not allowed. Some endpoints are not user specific and can be queried by anyone. For this case, use the respective OAuth flow in anonymous mode. It is important to note that OAuth 2.0 is only used for authentication and not for authorization, therefore the JWTs do not contain OAuth scopes!

All necessary information on usage and technical details of our specific implementation can be found in our Authentication Documentation.

Language

The Bookingtime API supports multiple languages on two levels. First, the language of the messages can be specified via the URL: api.bookingtime.com/app/v3/en

Supported languages:

Secondly, certain fields can contain a list of different translations that are used for display in modules. For example, in the appointmentTemplate, a list of multiple translations can be specified in the publicNameI18nListfield to enable multilingualism for end-user applications.

Prefixes for IDs

The following table represents our core entities with their assigned prefix. IDs are generated automatically and cannot be changed, this guarantees that IDs are unique and assignable. In contrast to the app API, not every entity was integrated into the module API for the sake of simplicity.

Permissions

Authenticated users are assigned various read and write permissions by linking employee to a employeeGroup. If a user has write permissions to an entity, he automatically gets read permissions to that entity as well.

The following endpoint lists all rights with their associated actions: listPermission

Additionally we listed the permissions for the app and module API in this article.

Regarding Server- und Client-JWT

The bookingtime API uses JWT to authenticate requests and provides two types of JWT authorization, server and client JWT.

For web apps, we recommend using a client JWT, a short-lived access token provided by our authorization server with the OAuth 2.0 protocol. To gain access using this method, you will need a regular bookingtime account.

For servers and other agents that use automated scripts to fetch data (e.g., to generate reports), we recommend to using a server JWT. To request a server JWT, a bookingtime developer account is required.

Most routes can be accessed using either authorization method. The are only a few exceptions which are referenced in the given endpoint descriptions. Additional authorizations are not required.

Additional Data

In the bookingtime application there are many entities that carry additonalDataobject. This can be used in various ways to optimize the bookingtime system to your individual business process. The additonalDataobject provides you with custom fields that can be unlocked during object creation. Each field is a key-value pair, where the value can be either a string, a number or a boolean, and the label is a string of your choice.

Inheritance

This is a feature aimed at companies where it is necessary to create many objects to represent the enterprise architecture. Entering the same basic information can be tedious, so we have built an inheritance function into our system. It allows you to link certain fields to their parent object and inherit its data values. All fields with the inheritance function set the values of the parent objects as default values and are therefore not required when creating a new instance.

One of the most common examples to benefit from inheritance is probably the address. For example, you may want to use all available meeting rooms in your building as a resource for your organization.

create an organization and enter the address to be inherited for each room.
create a resource, this will be the first room, so let's call it "Room A". The address should be inherited from the organization.
duplicate "Room A" and rename each record until you are done.
This way the address, which is always the same, has to be entered only once - when creating the organization.

Now we have rented a new building and want to move all the rooms to the new address. Since it is a new address, we would have to enter it for each individual resourcein the organization. If the inheritance setting is set to inherit from organization, we only need to update the address of the organization and each resourcewill show the new address. No further adjustments are needed.

The default setting for each inheritance field is "off", which means that this object needs its own value. If no value is specified upon creation (it is not a required option), the value of the parent entity will be used as default.

Important Note regarding HTTP Method LINK and UNLINK

In this documentation all endpoints with HTTP request methods LINK or UNLINK are specified with a HTTP request method of the type GET. For example linkFileAppointment and unlinkFileAppointment. This is incorrect and used due to a limitation of the documentation tool. All corresponding endpoints that utilize GET methods must be of type LINK or UNLINK.

Important Note regarding Time Range Limits

Availability for resources and appointment time slots are always confined to the current year and the subsequent year. Scheduling resources or appointments in the yesteryear is not possible.

E.g.: The current date is 10.01.2024, availabilities and appointments can be scheduled from 10.01.2024, until 31.12.2025.

Beginning with the next year, starting from 01.01.2025, availabilities and appointments can be scheduled for the years 2025 and 2026.