Use of this API requires a partner API Key. To obtain such a key, contact your Booxi representative.
Prior to use, consult Booxi's API fair use policy.
Remember that the URL at which you access the API depends on your hosting region. This article presents examples from a North American hosting only.
API documentation links:
The timeSlot API allows you to retrieve, create and delete time slots. It also allows you to tag time slots, which you can use to filter time slots shown to clients. Here are a few applications of this API.
The timeSlot API is currently limited to staff calendars.
Use Cases
Here are a few use cases where the timeSlot API and the property availabilityTags are used in concrete applications.
VIP Availability
Offer specific availability to VIP customers by creating available time slots assigned with a “VIP” tag. The Booking Widget can then be loaded with the property “availabilityTags:”VIP” to display only these time slots.
The same logic can be applied to “At Home” services or any other services for which availability is or should be limited.
Qualification Form
Ask your customers to fill out a qualification form and, based on their answers, generate a case code. Use that case code to load the Booking Widget with the appropriate tag and display matching availability.
Synchronize Calendars
Synchronize a Booxi calendar with data from an external source by creating busy time slots whenever a time slot is blocked in an external calendar. Or, synchronize available schedules from a time management system with a Booxi calendar by creating corresponding available time slots.
Create a New Time Slot in a Staff Calendar
First, a new time slot can be created in a staff calendar by using the POST /timeSlot API as per the details shown below. Make sure to provide your merchantId, a staffId, the type of time slot, either busy or available, a start and end time and, optionally, tags to further define this new time slot using the new property “availabilityTags”. Note that up to 10 tags for a maximum of 100 characters can be assigned to any calendar time slot, each tag must be separated with a comma.
Request URL for the North America
https://api.booxi.com/booking/v1/timeSlot
cURL
curl -X POST "https://api.booxi.com/booking/v1/timeSlot"
-H "accept: application/json"
-H "Content-Type: application/json" -d "{\"merchantId\":YOUR_MERCHANT_ID,\"staffId\":YOUR_STAFF_ID,\"type\":\"Available\",\"start\":\"2022-04-22T16:00:00Z\",\"end\":\"2022-04-22T20:00:00Z\",\"availabilityTags\":\"YOUR_TIMESLOT_TAGS\"}"
Request URL for Europe
https://api.booxi.eu/booking/v1/timeSlot
cURL
curl -X POST "https://api.booxi.eu/booking/v1/timeSlot"
-H "accept: application/json"
-H "Content-Type: application/json" -d "{\"merchantId\":YOUR_MERCHANT_ID,\"staffId\":YOUR_STAFF_ID,\"type\":\"Available\",\"start\":\"2022-04-22T16:00:00Z\",\"end\":\"2022-04-22T20:00:00Z\",\"availabilityTags\":\"YOUR_TIMESLOT_TAGS\"}"
The API’s response will be formatted as a JSON object.
Here’s an example of a successful JSON response.
{
"merchantId": 1002,
"staffId": 582,
"type": "Available",
"start": "2022-04-22T16:00:00Z",
"end": "2022-04-22T20:00:00Z",
"availabilityTags": "accessible,extended-hours"
}
You can test this API at the following links.
For North America | For Europe |
Find a Staff Availability Using availabilityTags
To retrieve a staff’s availability, use the GET /timeSlot API per the details shown below.
Your request must minimally include a staffId and a time range (start and end time in RFC3339 format). Then, by using the property “availabilityTags” you can further filter the results. Note that only results matching all tags will be returned. Other optional parameters are also available.
Request URL for North America
https://api.booxi.com/booking/v1/timeSlot?from=2022-10-22T16%3A00%3A00Z&to=2022-11-22T16%3A00%3A00Z&type=Available&availabilityTags=accessible%2Cextended-hours
cURL
curl -X GET "https://api.booxi.com/booking/v1/timeSlot?from=2022-10-22T16%3A00%3A00Z&to=2022-11-22T16%3A00%3A00Z&type=Available&availabilityTags=accessible%2Cextended-hours"
-H "accept: application/json"
Request URL for Europe
https://api.booxi.eu/booking/v1/timeSlot?from=2022-10-22T16%3A00%3A00Z&to=2022-11-22T16%3A00%3A00Z&type=Available&availabilityTags=accessible%2Cextended-hours
cURL
curl -X GET "https://api.booxi.eu/booking/v1/timeSlot?from=2022-10-22T16%3A00%3A00Z&to=2022-11-22T16%3A00%3A00Z&type=Available&availabilityTags=accessible%2Cextended-hours"
-H "accept: application/json"
You can test this API at the following links.
For North America | For Europe |
Here’s an example of a successful JSON response.
{
"timeSlots": [
{
"id": 12001,
"merchantId": 1002,
"ownerType": "Staff",
"staffId": 582,
"type": "Busy",
"start": "2022-04-19T14:00:00Z",
"end": "2022-04-19T14:15:00Z",
"canModify": true,
"description": "Break",
"availabilityTags": ""
},
{
"id": 12002,
"merchantId": 1002,
"ownerType": "Staff",
"staffId": 582,
"type": "Available",
"start": "2022-04-22T16:00:00Z",
"end": "2022-04-22T20:00:00Z",
"canModify": true,
"description": "",
"availabilityTags": "accessible,extended-hours"
}
],
"cursor": "tf_eJxjZGALcmVgYGdQTtjGAKJ9cvSBDNgBBjAAAFWgBPU"
}Each time slot is assigned a unique ID that can be later used to retrieve time slots individually through an API call.
Retrieve a Time Slot by Its ID
A specific time slot slot can be retrieved by using GET /timeSlot/ {timeSlotId}. The request must minimally include a valid timeSlotId as shown below.
Request URL for North America
https://api.booxi.com/booking/v1/timeSlot/12001
cURL
curl -X GET "https://api.booxi.com/booking/v1/timeSlot/12001"
-H "accept: application/json"
Request URL for Europe
https://api.booxi.com/booking/v1/timeSlot/12001
cURL
curl -X GET "https://api.booxi.com/booking/v1/timeSlot/12001"
-H "accept: application/json"
You can test this API at the following links.
For North America | For Europe |
Here’s an example of a successful JSON response for a single time slot.
{
"timeSlot": {
"id": 12001,
"merchantId": 1002,
"ownerType": "Staff",
"staffId": 582,
"type": "Busy",
"start": "2022-04-19T14:00:00Z",
"end": "2022-04-19T14:15:00Z",
"canModify": true,
"description": "Break",
"availabilityTags": ""
}
}
Delete a Time Slot by Its ID
Should you need to delete a specific time slot, you can do so by using DELETE /timeSlot/ {timeSlotId}. The request must minimally include a valid timeSlotId as shown below. Note that time slots starting more than 7 days in the past or more than 365 days in the future can’t be deleted. For more information, see here.
Request URL for North America
https://api.booxi.com/booking/v1/timeSlot/12001
cURL
curl -X DELETE "https://api.booxi.com/booking/v1/timeSlot/12001"
-H "accept: application/json"
Request URL for Europe
https://api.booxi.com/booking/v1/timeSlot/12001
cURL
curl -X DELETE "https://api.booxi.com/booking/v1/timeSlot/12001"
-H "accept: application/json"
You can test this API at the following links.
For North America | For Europe |
Common Properties
Property | Description | Example |
id | Unique identifier associated with a time slot. Can be used to retrieve a time slot individually. | "id": 12001 |
merchantId | The ID of the merchant a time slot is associated with. | "merchantId": 1002 |
ownerType | Ownership type. Only staff is supported for now. | "ownerType": "Staff" |
staffId | The ID of the staff a time slot belongs to. | "staffId": 582 |
type | Type of time slot, either “Busy” or “Available”. | "type":"Busy" |
start | Start time of a time slot in RFC3339 format. | "start": "2022-04-19T14:00:00Z" |
end | End time of a time slot in RFC3339 format. | "end": "2022-04-19T14:15:00Z" |
canModify | Can a time slot be modified? | "canModify": "true" |
description | A time slot’s description. | "description": "Summer time extended business hours” |
availabilityTags | Tags assigned to a time slot. Up to 10 tags for a maximum of 100 characters are supported for each time slot. | availabilityTags: "extended-hours" |