API V2.0

API Version 2.0

This page explains the capabilities of the API Version 2.0 and explains how to use it. 

2 API Access

To use the API you need to allow API ACCESS. Go to SETTINGS -> ACCOUNT -> ACCOUNT ACCESS and allow API access.

• The JSON functions can be created with a API and prop key which you set yourself in the Beds24 control panel {#fas:cog}} (SETTINGS)ACCOUNT and (SETTINGS) PROPERTIES > ACCESS

4 Scopes

Each category of API endpoint (except /authentication) requires the corrosponding scope to access.

Some categories have additional scopes that allow access to personal or financial information. For example, the "bookings" scope would grant access to a booking's basic information such as the check-in and checkout dates. To access personal information such as the name of a guest, the "bookings-personal" scope would be required. Similarly, to access the invoice of a bookings, the "bookings-financial" scope would be required.

Each scope must also have an acompanying method. For example "get:bookings" would grant read access to bookings, but in order to create a new booking "post:bookings" would be required.

The "all" method may be used as a shortcut to grant access to all methods. For example "all:bookings" would allow for the reading, updating, creating and deleting of bookings.

5 POST method

5.1 Creating/modifying multiple items

All POST endpoints accept an array of items (an item may be a booking, message, property etc).

It is possible to create and modify multiple different items in one request this way.

All existing "POSTable" items will have an "id" field to uniquely identify it.

• To create a new item, just do not include an id.
• To modify an existing item, include its id.

5.2 Subitems

Some items can contain subitems. For example, a booking may contain an "invoice item" and an "info item".

Subitems generally work in the same way as their parent items.

To add a new subitem to an item, include the subitem without an id.

Example: add a new info item to a booking:
{
   "id": {bookingId},
   "infoItems": [
       {
           "code": "this will create",
           "text": "a new info item"
       }
   ]
}

To update an existing subitem, include the subitem's id.

Example: update a booking's info item:
{
   "id": {bookingId},
   "infoItems": [
       {
           "id": {infoItemId},
           "text": "this info item will have its text changed"
       }
   ]
}

To delete a subitem, include only the subitem's id.

Example: delete a booking's info item:
{
   "id": {bookingId},
   "infoItems": [
       {
           "id": {infoItemId},
       }
   ]
}

5.3 Responses

All POST requests will have a standard response.

5.3.1 Structure

Responses will be an array containing a number of response items equal to the number of items in the request.

Each response item will contain a "success" field, and may contain a "modified", "errors", "warnings" or "info" field (these are not mutually exclusive).

5.3.1.1 Order of response items

The order of the items in the response will correspond to the order that items were sent in the request.

Example: POST two message for different bookings:
   [
       {
           "bookingId": 1111111,
           "message": "a message"
       },
       {
           "bookingId": 2222222,
           "message": "a different message"
       },
   ]

Example: response order for the above request:
   [
       {
           "success": true,
           "info": [
               {
                   "message": "information about the message for booking 1111111"
               }
           ]
       },
       {
           "success": false,
           "errors": [
               {
                   "message": "an error about the message for booking 2222222"
               }
           ]
       }
   ]

6 Examples

6.1 Authentication

6.1.1 Refreshing a token

Request:

curl -X 'GET' \
  'https://api.example.com/v2/authentication/token' \
  -H 'accept: application/json' \
  -H 'refreshToken: Ea6DftE50aYYRe/qAd9SkQaSmTF6kaLQxH6gtRxO1h10yVC64d4qIj4BGiQOU+y5'

Response:

{
  "token": "wEoJHQIwRrLwHqTqAsn0/XjzaZkVk4E8sSDwbRN2HKDlulkt6n7aHQCcvdqfX+y5",
  "expiresIn": 3600
 }