Skip to main content

How to use the module API

Alex B.
Updated

Introduction

This guide shows developers how to access the bookingtime Module API for testing purposes. The bookingtime platform uses 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.

If not already created, a Developer Account is needed for authentication.

 

Unauthenticated requests are not allowed.

 

Please note that the Client Credentials Flow must not be used in single page applications (SPAs) and native applications under any circumstances, unless you are using a testing application that is intended to be deleted later. The client secret must be kept confidential and static client secrets could easily be extracted by third parties!

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

 

Overview

Making requests to the bookingtime platform requires that your application is authenticated and authorized to access data. Your application can be authenticated in two ways:

  • App Authentication: bookingtime authorizes your application to access the bookingtime platform.
    Using the Client Credentials Flow.
  • User Authentication: bookingtime, as well as the user, grant your application permission to access and/or modify data.
    Using the Authorization Code Flow.

oauth-intro.png

The tokens and Ids mentioned in this guide should be replaced by the values your getting as responses. The organizationId can be found in the URL, while using the software.

 

In both cases, the bookingtime authorization server responds first with an refresh token, which then can be exchanged for an access token:

  {
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJleHBpcmVkX3N0b3J5IjoicmVhZ3JvdXAiLCJpYXQiOjE2MjYwNzg1NzgsInN1YiI6InVzZXIxMjM0NTYifQ.2oP0M1Xm7bbkXQz47fuMzOa5qV7yo-dQfxThymfg2PQ",
    "token_type": "Bearer",
    "expires_in": "<time in s>"
  }
  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJleHBpcmVkX3N0b3J5IjoicmVhZ3JvdXAiLCJpYXQiOjE2MjYwNzg1NzgsInN1YiI6InVzZXIxMjM0NTYifQ.2oP0M1Xm7bbkXQz47fuMzOa5qV7yo-dQfxThymfg2PQ",
    "token_type": "Bearer",
    "expires_in": "<time in s>"
  }

These tokens are a JSON Web Tokens and their full structure can be seen here. A valid access token allows you to query the bookingtime API:

    curl -H "Authorization: Bearer eyJhbG..."
    https://api.bookingtime.com/app/v3/

At this point, your request should be authenticated, but your app/user may not be permitted to access a specific endpoint.

Your application must be explicitly allowed to access a specific organization and users have various read and write permissions.

You simply want to try out our API or test possible integrations with your system without too much effort?
In this case, we recommend the usage of the Client Credential Flow. The Client Credentials Flow is used for machine-to-machine authentication and therefore does not need any user interaction.

After creating a new app in the developer service, you will receive a Client ID and Client Secret, which you can use to authenticate your own app. This gives you access to a demo organization and allows you to use all common functions of the bookingtime system. Only user specific endpoints are not allowed. Please note that this is only a recommendation for prototypes to reduce the implementation complexity. The use of the Client Credentials Flow may not be allowed for your use case.

Alternatively, you are free to implement the Authorization Code Flow.

 

Request access to the API

Register a developer account at the bookingtime developer service.

 

How to use the Module API

In this example, we use the client credentials flow to book your first appointment with the Module API. In the process, we go through each necessary request until a valid booking is made in your demo organization.

The following credentials are required:

 

Client ID Unique ID of your custom module
Client Secret Empty or omitted in this case
Organization ID Unique token of your demo organization

Have your application request authentication

To request access tokens, an application must make a POST request to the oauth/token endpoint for a client credential to refresh token exchange. However, no client secret is necessary for the Module API, see Client Credentials Flow for more information.

Example Request:

  POST /oauth/token HTTP/1.1
  Host: auth.bookingtime.com
  Authorization: Bearer eyJhbGc... https://api.bookingtime.com/app/v3/
  Content-Type: application/json
  Content-Length: 77
  
  {"grant_type":"client_credentials", "client_id":"23...YOUR_CLIENT_ID"}  

curl -X POST \
    -H "Authorization: Bearer eyJhbGc... https://api.bookingtime.com/app/v3/" \
    -H "Content-Type: application/json" \
    -d grant_type=client_credentials \
    -d client_id=23...YOUR_CLIENT_ID \
    https://auth.bookingtime.com/oauth/token

Example Response:

  {
    "refresh_token": "eyJ0eX...",
    "token_type": "Bearer",
    "expires_in": 1800
  }

Exchange refresh token for organization specific access token

Again, send a POST request to the oauth/token endpoint, but this time with the refresh token and the ID of a organization your module is permitted to access.

Example Request:

  POST /oauth/token HTTP/1.1 Host: auth.bookingtime.com Authorization:
  Bearer eyJhbGc... https://api.bookingtime.com/app/v3/ Content-Type: application/json
  Content-Length: 123 

grant_type=refresh_token&client_id=23...YOUR_CLIENT_ID&refresh_token=eyJ0eX...&organization_id=f6123456789101112131415aBCdeFgH
curl -X POST \
  -H "Authorization: Bearer eyJhbGc... https://api.bookingtime.com/app/v3/" \
  -H "Content-Type: application/json" \
  -d grant_type=refresh_token \
  -d client_id=23...YOUR_CLIENT_ID \
  -d refresh_token=eyJ0eX... \
  -d organization_id=f6123456789101112131415aBCdeFgH \
  https://auth.bookingtime.com/oauth/token

Example Response:

  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJleHBpcmVkX3N0b3J5IjoicmVhZ3JvdXAiLCJpYXQiOjE2MjYwNzg1NzgsInN1YiI6InVzZXIxMjM0NTYifQ.2oP0M1Xm7bbkXQz47fuMzOa5qV7yo-dQfxThymfg2PQ",
    "token_type": "Bearer",
    "expires_in": 300
  }

List available booking templates

The received access token is valid for 5 minutes and allows you to make authenticated requests to the bookingtime App API endpoints. First, load a list with the booking templates of your demo organization and save the ID of one of the two existing booking templates.

Example Request:

  POST /oauth/token HTTP/1.1
  Host: auth.bookingtime.com
  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJleHBpcmVkX3N0b3J5IjoicmVhZ3JvdXAiLCJpYXQiOjE2MjYwNzg1NzgsInN1YiI6InVzZXIxMjM0NTYifQ.2oP0M1Xm7bbkXQz47fuMzOa5qV7yo-dQfxThymfg2PQ https: //api.bookingtime.com/app/v3/
  Content-Type: application/json
  Content-Length: 72
  
  grant_type=client_credentials&client_id=2312345678899874561231234567891

  curl -X "GET" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJleHBpcmVkX3N0b3J5IjoicmVhZ3JvdXAiLCJpYXQiOjE2MjYwNzg1NzgsInN1YiI6InVzZXIxMjM0NTYifQ.2oP0M1Xm7bbkXQz47fuMzOa5qV7yo-dQfxThymfg2PQ"
    https://api.bookingtime.com/module/v3/de/organization/f6123456789101112131415aBCdeFgH/bookingTemplate/list

Example Response:

  {
    "messageList": [],
    "content": {
    "class": "LIST",
    "recordTotal": 12,
    "recordLimit": 9999,
    "recordList": [
        {
            "class": "BOOKING_TEMPLATE",
            "id": "fc12345678910AbcDefGh1112",
            "customId": "",
            "name": "Test AppointmentTemplate",
            "nameI18nList": [],
            "location": "ORGANIZATION_ADDRESS",
            "image": "",
            "duration": 60,
            "leadTime": 0,
            "followupTime": 0,
            "price": {
                "class": "PRICE",
                "priceGross": 99.99,
                "taxRate": 19,
                "currency": "EUR"
            },
            "showPrice": true,
            "priceGross": 99.99,
            "currency": "EUR",
            "taxRate": 19,
            "description": "Zeile1 Zeile2",
            "descriptionI18nList": [],
            "appointmentAddressRequired": false,
            "customerAddressRequired": false,
            "customerEmailRequired": true,
            "customerMobileRequired": false,
            "additionalCustomerCountMax": 0,
            "bookingDayEarliest": 0,
            "bookingDayLatest": 14,
            "bookingLeadTime": 120,
            "address": {
                "class": "ADDRESS",
                "name": "Example Company",
                "extra": "",
                "street": "Street 1",
                "zip": "12345",
                "city": "New York",
                "country": "DE",
                "geoCoordinates": {
                    "class": "GEO_COORDINATES",
                    "latitude": 42.60389747,
                    "longitude": 8.980361
                }
            },
            "bookingStepList": [],
            "emailTemplateList": [{
                "class": "EMAIL_TEMPLATE",
                "id": "46Ytcdub4EjAxuxZ25iIFvkCkIDau0VF",
                "customId": "",
                "name": "Aftersale E-Mail",
                "event": "APPOINTMENT_END"
            }],
            "smsTemplateList": [{
                "class": "SMS_TEMPLATE",
                "id": "6GmkLGvDF36kLB9SvV4dvIpU4V4Jr8qM",
                "customId": "",
                "name": "After customer-start",
                "event": "APPOINTMENT_CUSTOMER_START"
            }],
            "extraFieldList": [],
            "additionalData": null
        },
  },{
        "class": "BOOKING_TEMPLATE",
        "id": "fc123456789101112131415aBCdeFgH",
        "customId": "4321",
        "name": "Demo Appointment 2",
        "duration": 60,
    ...
  }],
  ...

Get the earliest booking slot

With the help of the booking template ID you can display the first possible booking slot. Other possible requests, such as displaying all bookable slots of a certain week, can be found in our Module API documentation. Here you want to save the ID of a booking slot.

Example Request:


GET /module/v3/de/organization/fc123456789101112131415aBCdeFgH/bookingTemplate/fc123456789101112131415aBCdeFgH/bookingSlot/earliest HTTP/1.1
Host: api.bookingtime.com

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJleHBpcmVkX3N0b3J5IjoicmVhZ3JvdXAiLCJpYXQiOjE2MjYwNzg1NzgsInN1YiI6InVzZXIxMjM0NTYifQ.2oP0M1Xm7bbkXQz47fuMzOa5qV7yo-dQfxThymfg2PQ


  curl -X "GET" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJleHBpcmVkX3N0b3J5IjoicmVhZ3JvdXAiLCJpYXQiOjE2MjYwNzg1NzgsInN1YiI6InVzZXIxMjM0NTYifQ.2oP0M1Xm7bbkXQz47fuMzOa5qV7yo-dQfxThymfg2PQ"
  https://api.bookingtime.com/module/v3/de/organization/f6...YOUR_ORGANIZATION_ID/bookingTemplate/fc123456789101112131415aBCdeFgH/bookingSlot/earliest

Example Response:

  {
    "rangeStart": "2021-01-01T08:00:00+02:00",
    "rangeEnd": "2021-01-02T08:15:00+02:00",
    "timeZone": "Europe/Berlin",
    "bookingSlotList": [{
        "class": "BOOKING_SLOT",
        "id": "4f6gl70xpd71eqiz0878651d90b04330",
        "timestamp": "2021-01-01T00:15:00+02:00",
        "bookingResourceCombination": ["browuBQJWSylERkRQIHHrlXHVpCeyfqN"]
    }, {
        "class": "BOOKING_SLOT",
        "id": "4f123456789101112131415aBCdeFgH",
        "timestamp": "2021-01-01T00:15:00+02:00",
        "bookingResourceCombination": ["br.."]
    }]
  }

Book your first appointment

Now you have everything you need to book your first appointment! Send a POST request to the Add Appointment endpoint, with a valid booking slot ID and some data about the customer in the request body, to book this appointment bindingly and blocking linked staff and/or resources for this time period.

Example Request:


POST /module/v3/de/organization/f6123456789101112131415aBCdeHg/appointment/add HTTP/1.1
Host: api.bookingtime.com
Authorization: Bearer eyJhbGc... https://api.bookingtime.com/app/v3/
Content-Type: application/json
Content-Length: 128

{"bookingSlotId":"4f123456789101112131415aBCdeFgH", "customer":{"firstName":"John", "lastName":"Doe", "email":"jd@scrubs.doc"}}

  curl -X "POST" \
    -H "Authorization: Bearer eyJhbGc... https://api.bookingtime.com/app/v3/" \
    -H "Content-Type: application/json" \
    -d '{"bookingSlotId":"4f123456789101112131415aBCdeFgH", "customer":{"firstName":"John", "lastName":"Doe", "email":"jd@scrubs.doc"}}'
    https://api.bookingtime.com/module/v3/de/organization/f6123456789101112131415aBCdeFgH/appointment/add

Example Response:

  {
    "class": "APPOINTMENT",
    "id": "ed123456789101112131415aBCdeFgH",
    "start": "2021-01-01T00:15:00+02:00",
    "end": "2021-01-01T00:45:00+02:00",
    "duration": 30,
    "name": "Demo Appointment 1",
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "jd@scrubs.doc"
        ...
    },
    ...
  }

Related articles

Comments

0 comments

Please sign in to leave a comment.