跳到主要內容

Bookings ONE External Api (v1)

Download OpenAPI specification:Download

Bookings ONE External API allow developers to interact with their team's data (such as locations, spaces, presence, etc.) and build third-party applications to extend Bookings ONE's capabilities.

Introduction

This API documents is an reference for integration with Bookings ONE server. These External APIs allow third party application to access Bookings one for data communication. There are serval scenarios that will highly depend on the Bookings ONE API integration, such as IoT sensor integration, access control integration, data analytics etc.

All these API are running in HTTPs RESTful request.

Authentication

Bookings ONE offers authentication through the API authentication:

Navigate to Management console -> Settings -> API authentication, and create the API access token for authentication. The Bookings ONE APIs use this access token to authenticate incoming requests. You can view and manage your access token in the Bookings ONE Management console.

Find out how to create access token for API authentication.

These access tokens contain many privileges, thus make sure to keep them secure and do not share these access token in public accessible site such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g. for a cross-origin request), use

-H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXXX".

All API requests must be made over HTTPS. Calls made over plain HTTP will be auto redirect to HTTPS. API requests without authentication will be treated as fail and return 401 errors. Example:

curl -v -L -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXXX" -H "Content-Type: application/json"  "https://{your bookings one server address}/API/external/system/v1/information"

Security & Access control

There are serval security practices that can be done to protect your application from vicious network attack on the Bookings ONE integration:

  1. Access token will only show once when it is generated, and it will not be shown again in anywhere and anytime afterwards. After you refresh the page, if you have lost the key, you need to go back to the management console to regenerate a new token for replacement.

  2. If you have more than 1 application which would like to connect to Bookings ONE, you can create new keys for each application. Please do not use the same key for different applications.

  3. You can restrict the access by limiting the sender IP address. Following are the valid format:

    • 225.154.33.1
    • 225.154.33.1-100
    • 225.154.33.3, 225.154.33.100
    • 225.154.33.0/24
  4. You can also set expire time to make sure the authentication key will not be effective for certain period of time.

Find out how to apply above setting for an access token.

Add new APIs

If you find out that the existing APIs are not enough for your use case, please send a email to hello@ones.software and provide further information of your case, we will consider to add new APIs to Bookings ONE to fit your story.

System

This section of APIs provide the common system information of Bookings ONE.

Get system information

System information of Bookings ONE

Responses

Response samples

Content type
application/json
{
  • "name": "Bookings ONE",
  • "version": "2.2.0",
  • "environment": "Production",
  • "clientName": "Happy Ltd."
}

VisitorManagement

This section of APIs provide the communication interface for information of visitor.

Get visitor badge information

Getting the visitor badge information by id / uid

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "uid": "string",
  • "period": {
    },
  • "registrationCode": "FJUEIW",
  • "state": 0,
  • "visitor": {
    },
  • "checkInDate": "2021-01-03T12:00:00+08:00",
  • "checkOutDate": "2021-01-03T14:00:00+08:00"
}

Search visitor badge information

Search the visitor badge information

query Parameters
id
string

ID of Visitor badge, accept multiple separate by ',' e.g. 1,2,3

uid
string

UID of Visitor badge, accept multiple separate by ','

from
string

Specify the start time to search resource appointment, accept ISO 8601 (2015-01-01T08:00:00+08:00) or string 'now'

to
string

Specify the start time to search resource appointment, accept ISO 8601 (2015-01-01T08:00:00+08:00) or string 'now'

registrationCode
string

Registration code of Visitor badge, accept multiple separate by ',' e.g. ABCDEF,BCDEFG

buildingId
string

BuildingId of Visitor badge, accept multiple separate by ',' e.g. 1,2,3

state
string

State of Visitor badge, accept multiple separate by ',' e.g. initial,noShow,visited,visiting

page
integer <int32>
row
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metaData": {
    }
}

VisitingAppointment

This section of APIs provide the communication interface for information of visiting appointment.

Search visitor appointment information

Search the visitor appointment information

query Parameters
id
string

ID of Appointments, accept multiple separate by ','

from
string

Specify the start time to search resource appointment, accept ISO 8601 (2015-01-01T08:00:00+08:00) or string 'now'

to
string

Specify the start time to search resource appointment, accept ISO 8601 (2015-01-01T08:00:00+08:00) or string 'now'

invitingUserId
string

ID of appointment inviter, accept multiple separate by ',' , e.g. 1,2,3

searchText
string

Search by the appointment subject and content

bookingState
string

Specify the booking state, return all if this is not provided. accept multiple separate by ',' , e.g. booked,using,waitingCheckIn

bookableResourceId
string

ID of Bookable resource, accept multiple separate by ',' , e.g. 1,2,3

buildingId
string

ID of building, accept multiple separate by ',' , e.g. 1,2,3

visitorId
string

ID of visitor, accept multiple separate by ',' , e.g. 1,2,3

bookingId
string

ID of booking, accept multiple separate by ',' , e.g. 1,2,3

page
integer <int32>

page

row
integer <int32>

row

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metaData": {
    }
}

User

This section of APIs provide the communication interface for information of users.

Get user by id

path Parameters
id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "displayName": "string",
  • "emailAddress": "string",
  • "userName": "string",
  • "isActivated": true,
  • "userGroups": [
    ],
  • "actualPermissions": [
    ],
  • "isDeleted": true
}

Search users by pagination

query Parameters
id
string

Service item ids specified, e.g. 1,2,3

userGroupId
string

Search by the user group id id e.g. 1,2,3

searchText
string

Search by the bookable resource name

isDeleted
boolean

Search if the bookable resource is deleted

page
integer <int32>

Pages of request. If this is not provided, will return first page

row
integer <int32>

Number of rows for each page. If this is not provided, default value will be 50.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metaData": {
    }
}

ServiceItem

This section of APIs provide the communication interface for information of service item.

Get service item by id

path Parameters
id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": [
    ],
  • "description": [
    ],
  • "type": 0,
  • "isDeleted": true,
  • "actualAssignedUsers": [
    ]
}

Search service items by pagination

query Parameters
id
string

Service item ids specified, e.g. 1,2,3

type
string

Service item type, accept multiple separate by ',' , e.g. betweenBooking,afterBooking

servicePlanId
string

Search by the service plan id id e.g. 1,2,3

searchText
string

Search by the bookable resource name

page
integer <int32>

Pages of request. If this is not provided, will return first page

row
integer <int32>

Number of rows for each page. If this is not provided, default value will be 50.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metaData": {
    }
}

IotSensorData

This section of APIs provide the communication interface for IoT sensor to Bookings ONE.

Post occupancy sensor data

Update the occupancy sensor occupancy information

Request Body schema:

Sensor data

accessId
required
string

Access ID of the related Iot Device

timestamp
string or null <date-time>

Time of the data collected by sensor. If empty, system will use the time data received by the system.

object or null

Data from occupancy sensor.

There are two data are required:

isConnected bool: which is specified for sensor is connected or not;

isOccupied bool: which is specified for sensor is occupied or not;

Example: { "isConnected": true, "isOccupied": true }

Responses

Request samples

Content type
{
  • "accessId": "4GHUG6",
  • "timestamp": "2022-01-12T12:23:02+08:00",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "deviceId": 10,
  • "timestamp": "2022-01-12T12:23:02+08:00",
  • "data": {
    }
}

Post occupancy sensor data

Update the occupancy sensor occupancy information

Request Body schema:

Sensor data

accessId
required
string

Access ID of the related Iot Device

timestamp
string or null <date-time>

Time of the data collected by sensor. If empty, system will use the time data received by the system.

object or null

Data from occupancy sensor.

There are two data are required:

isConnected bool: which is specified for sensor is connected or not;

isOccupied bool: which is specified for sensor is occupied or not;

Example: { "isConnected": true, "isOccupied": true }

Responses

Request samples

Content type
{
  • "accessId": "4GHUG6",
  • "timestamp": "2022-01-12T12:23:02+08:00",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "deviceId": 10,
  • "timestamp": "2022-01-12T12:23:02+08:00",
  • "data": {
    }
}

IotDevice

This section of APIs provide the communication interface for information of iot device.

Search iot devices by pagination

query Parameters
id
string

Iot device ids specified, e.g. 1,2,3

accessId
string

Iot device accessIds specified e.g. Room101,Desk101

searchText
string

Search by the iot device name

bookableResourceId
string

Search by the bookable resource id e.g. 1,2,3 or null

isDeleted
boolean

Search if the iot device is deleted

page
integer <int32>

Pages of request. If this is not provided, will return first page

row
integer <int32>

Number of rows for each page. If this is not provided, default value will be 50.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metaData": {
    }
}

Create iot device

Request Body schema:

Iot device to be create

id
integer <int32>

Bookable resource Id

accessId
string or null

Access Id

name
string or null

IotDevice name

object (Server.ExternalInterface.Features.IotDevice.IotDeviceViewModel+BookableResourceViewModel)
isDeleted
boolean

Is the iot device deleted

Responses

Request samples

Content type
{
  • "id": 0,
  • "accessId": "string",
  • "name": "string",
  • "bookableResource": {
    },
  • "isDeleted": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "accessId": "string",
  • "name": "string",
  • "bookableResource": {
    },
  • "isDeleted": true
}

Update iot device

path Parameters
id
required
string

Iot device ids specified, e.g. 1,2,3

Request Body schema:

Iot device to be create

id
integer <int32>

Bookable resource Id

accessId
string or null

Access Id

name
string or null

IotDevice name

object (Server.ExternalInterface.Features.IotDevice.IotDeviceViewModel+BookableResourceViewModel)
isDeleted
boolean

Is the iot device deleted

Responses

Request samples

Content type
{
  • "id": 0,
  • "accessId": "string",
  • "name": "string",
  • "bookableResource": {
    },
  • "isDeleted": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "accessId": "string",
  • "name": "string",
  • "bookableResource": {
    },
  • "isDeleted": true
}

Get iot device by id

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "accessId": "string",
  • "name": "string",
  • "bookableResource": {
    },
  • "isDeleted": true
}

EPaperController

This section of APIs provide the communication interface for information of building.

Get building by id

path Parameters
id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "EPaperController 1",
  • "displayLanguage": "en-US",
  • "tags": [
    ]
}

Search building by pagination

query Parameters
id
string

EPaperController ids specified, e.g. 1,2,3

isDeleted
boolean

Search if the building is deleted

type
string

E Paper controller type, accept multiple separate by ',' , e.g. qbicGateway or MinewServer

searchText
string

Search by the building name

page
integer <int32>

Pages of request. If this is not provided, will return first page

row
integer <int32>

Number of rows for each page. If this is not provided, default value will be 50.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metaData": {
    }
}

Search building by pagination

Request Body schema:

Update e-paper tag status request

batteryLevel
number or null <double>

Battery Level of the device

screenSize
number or null <double>

ScreenSize

isOnline
boolean

Is the tag online

ePaperTagId
string or null

Id of e paper tag

Responses

Request samples

Content type
{
  • "batteryLevel": 99,
  • "screenSize": 4,
  • "isOnline": true,
  • "ePaperTagId": "true"
}

Response samples

Content type
application/json
{
  • "isSuccess": true
}

Dashboard

This section of APIs provide the communication interface for information of various data analytics on dashboard.

Get daily visitor analytics result

Getting the daily visitor analytics result of Bookings ONE

query Parameters
date
required
string <date-time>

Date contain two information date and the offset

Since Bookings ONE are running in global server, it will not have information which the request's timezone are, it is necessary to specify the offset of your request timezone.

time value are not relevant at this case, just state the value as 00:00:00.

Example: 2022-01-05T00:00:00+08:00

Responses

Response samples

Content type
application/json
{
  • "numberOfInitial": 10,
  • "numberOfVisiting": 15,
  • "numberOfVisited": 6,
  • "numberOfNoShow": 3
}

Get daily visitor analytics result

Getting the daily visitor analytics result of Bookings ONE

query Parameters
date
required
string <date-time>

Date contain two information date and the offset

Since Bookings ONE are running in global server, it will not have information which the request's timezone are, it is necessary to specify the offset of your request timezone.

time value are not relevant at this case, just state the value as 00:00:00.

Example: 2022-01-05T00:00:00+08:00

Responses

Response samples

Content type
application/json
{
  • "numberOfInitial": 10,
  • "numberOfVisiting": 15,
  • "numberOfVisited": 6,
  • "numberOfNoShow": 3
}

Building

This section of APIs provide the communication interface for information of building.

Get building by id

path Parameters
id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": [
    ],
  • "address": "string",
  • "shortName": "string",
  • "floors": [
    ],
  • "isDeleted": true,
  • "order": 0
}

Search building by pagination

query Parameters
id
string

Building ids specified, e.g. 1,2,3

isDeleted
boolean

Search if the building is deleted

searchText
string

Search by the building name

page
integer <int32>

Pages of request. If this is not provided, will return first page

row
integer <int32>

Number of rows for each page. If this is not provided, default value will be 50.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metaData": {
    }
}

Booking

This section of APIs provide the communication interface for booking information of bookable resource.

Get resource appointments

Getting the appointment of bookable resources in Bookings ONE

query Parameters
id
string

ID of Appointments, accept multiple separate by ','

from
string

Specify the start time to search resource appointment, accept ISO 8601 (2015-01-01T08:00:00+08:00) or string 'now'

to
string

Specify the start time to search resource appointment, accept ISO 8601 (2015-01-01T08:00:00+08:00) or string 'now'

organizerUserId
string

ID of appointment organizer, accept multiple separate by ',' , e.g. 1,2,3

searchText
string

Search by the appointment subject and content

bookingState
string

Specify the booking state, return all if this is not provided. accept multiple separate by ',' , e.g. booked,using,waitingCheckIn

bookableResourceId
string

ID of Bookable resource, accept multiple separate by ',' , e.g. 1,2,3

bookableResourceType
string

Type of Bookable resource, accept multiple separate by ',', e.g. room, desk

bookingId
string

ID of booking, accept multiple separate by ',' , e.g. 1,2,3

excludePreparation
boolean

Exclude preparation appointments

page
integer <int32>

page

row
integer <int32>

row

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metaData": {
    }
}

Export bookings by bookable resource to Excel

If no time zone is specified, UTC time is used

         Following API is still under construction. Will be released in coming version and the format may be changed based on development..
query Parameters
From
string <date-time>
Example: From=2021-10-11T11:00:00+08:00

Start time of the period

To
string <date-time>
Example: To=2021-10-11T14:00:00+08:00

End time of the period

TimeZone
string
Example: TimeZone=Asia/Hong_Kong

Time zone name

Responses

BookableResource

This section of APIs provide the communication interface for information of bookable resource.

Get bookable resource by id

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "accessId": "string",
  • "name": [
    ],
  • "type": 0,
  • "category": 0,
  • "description": [
    ],
  • "actualServiceItems": [
    ],
  • "floor": {
    },
  • "capacity": 0,
  • "isDeleted": true
}

Search bookable resources by pagination

query Parameters
id
string

Bookable resource ids specified, e.g. 1,2,3

type
string

Bookable resource type, accept multiple separate by ',' , e.g. room,desk,equipment

category
string

Bookable resource category, accept multiple separate by ',' ,e.g. meetingRoom,phoneBooth

accessId
string

Bookable resource accessIds specified e.g. Room101,Desk101

isDeleted
boolean

Search if the bookable resource is deleted

searchText
string

Search by the bookable resource name

floorId
string

Search by the floor id e.g. 1,2,3 or null

minCapacity
integer <int32>

Search where the capacity are larger than the value provided

maxCapacity
integer <int32>

Search where the capacity are less than the value provided

page
integer <int32>

Pages of request. If this is not provided, will return first page

row
integer <int32>

Number of rows for each page. If this is not provided, default value will be 50.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metaData": {
    }
}

Subscribe resource appointment change

Subscribe any booking change on the booking resource

Request Body schema:

Specify the ID of Bookable resource. e.g. 1,2,3

ids
required
string

Specify the ID to subscribe

callbackUrl
required
string

The url that will call back when there are any update from system

expireTime
required
integer <int32>

Expire time in minutes. Default value is 60, maximum value is 1440 (1day)

Responses

Request samples

Content type
{
  • "ids": "1,2,3",
  • "callbackUrl": "string",
  • "expireTime": 0
}

Response samples

Content type
application/json
"string"

BookableResourcePlayerContent

This section of APIs provide the communication interface for information of bookable resource.

Search bookable resources by pagination

query Parameters
id
string

Bookable resource ids specified, e.g. 1,2,3

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Subscribe resource appointment change

Subscribe any booking change on the booking resource

Request Body schema:

Specify the ID of Bookable resource. e.g. 1,2,3

ids
required
string

Specify the ID to subscribe

callbackUrl
required
string

The url that will call back when there are any update from system

expireTime
required
integer <int32>

Expire time in minutes. Default value is 60, maximum value is 1440 (1day)

Responses

Request samples

Content type
{
  • "ids": "1,2,3",
  • "callbackUrl": "string",
  • "expireTime": 0
}

Response samples

Content type
application/json
"string"

BookableResourceAccessKey

This section of APIs provide the communication interface for information of bookable resource.

Search bookable resources by pagination

query Parameters
bookableResourceId
string

Bookable resource ids specified, e.g. 1,2,3

type
string

Specify the type e.g. oneTime,static,daily

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Subscribe resource appointment change

Subscribe daily access key change on the booking resource

Request Body schema:

Specify the ID of Bookable resource. e.g. 1,2,3

ids
required
string

Specify the ID to subscribe

callbackUrl
required
string

The url that will call back when there are any update from system

expireTime
required
integer <int32>

Expire time in minutes. Default value is 60, maximum value is 1440 (1day)

Responses

Request samples

Content type
{
  • "ids": "1,2,3",
  • "callbackUrl": "string",
  • "expireTime": 0
}

Response samples

Content type
application/json
"string"

Subscribe resource appointment change

Subscribe daily access key change on the booking resource

Request Body schema:

Specify the ID of Bookable resource. e.g. 1,2,3

ids
required
string

Specify the ID to subscribe

callbackUrl
required
string

The url that will call back when there are any update from system

expireTime
required
integer <int32>

Expire time in minutes. Default value is 60, maximum value is 1440 (1day)

Responses

Request samples

Content type
{
  • "ids": "1,2,3",
  • "callbackUrl": "string",
  • "expireTime": 0
}

Response samples

Content type
application/json
"string"