How to Use the timeSlot API

The following article will explain how to use the timeSlot API calls and present a few of its applications.

The following article will explain how to use the timeSlot API calls and present a few of its applications.

Disclaimer: the timeSlot API is limited to staff calendar at this time.

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 you 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”. Take 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.

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. Take 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.

 

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"
}

Take note that 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.

 

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. Take 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 further details, consult the API documentation at the links provided at the end of this article.

 

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.

 

References

For more information about Booxi APIs and their usage, please refer to the following links:

Europe: https://api.booxi.eu/doc/booking.html

Americas: https://api.booxi.com/doc/booking.html

Where to find API keys:

• Your Merchant API key can be found in the back office, section My Business / Business Details.
• Your Partner API key must be requested to your Booxi Account Manager. The Partner API key must only be used in server-side (backend) code to keep it a secret.

Common Properties