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:
Use Cases
Here are a few cases where the GET/calendar API endpoint is used in practical applications.
Staff Calendar Application
Fetch all entries from a staff’s calendar and present the results in an interface or application accessible by the staff to provide a summary of upcoming events.
Custom Clienteling Application
Fetch all bookings for a specific date and staff member, display results in a clienteling application so clients can visualize their preferred staff’s availability.
Fetching Events From a Staff’s Calendar
To fetch the content of a staff’s calendar, use the GET /calendar endpoint as per the details below. Your request must minimally include a start and end date, a valid staff ID, the type of events to fetch and the referenced objects to include in the response.
Mandatory Parameters
Parameter | Format | Description |
from | from=date | Query’s starting date, in RFC3339 format. The starting date is inclusive. This parameter is required when the cursor is null. |
to | to=date | Query’s ending date, in RFC3339 format. The ending date is also inclusive. This parameter is required when the cursor is null. |
staffId | staffId=ID | The ID associated with the staff the query is made for. Required when the cursor is null. |
eventType | eventType=type | The event type to fetch. Supported types are “Appointment”, “GroupEvent” and “TimeSlot”. This parameter is required when the cursor is null. The parameter must be repeated in the query for each type to fetch. |
include | include=type | The type of events. Supported values: Appointment only. Required when the cursor is null. The parameter must be repeated for each type to include. |
Optional Parameters
Parameter | Format | Description |
language | language=lng | The language code that the content should be in. Consult our API documentation to see which languages are supported.
|
cursor | cursor=string | A token to get the next set of results. When the cursor is set, all other query parameters should NOT be set. |
Limitations
Starting date cannot be more than 7 days in the past.
Request URL for the North America
https://api.booxi.com/booking/v1/calendar
cURL
curl -X GET "https://api.booxi.com/booking/v1/calendar?from=2023-11-11T09%3A00%3A00Z&to=2023-11-12T09%3A00%3A00Z&staffId=YOUR_STAFF_ID&eventType=Appointment&include=Appointment"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
Request URL for Europe
https://api.booxi.eu/booking/v1/calendar
cURL
curl -X GET "https://api.booxi.eu/booking/v1/calendar?from=2023-11-11T09%3A00%3A00Z&to=2023-11-12T09%3A00%3A00Z&staffId=YOUR_STAFF_ID&eventType=Appointment&include=Appointment"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include all calendar entries associated with the specified staff, for the specified type, for the range of time provided.
Here’s an example of a successful response:
{
"calendarEvents": [
{
"id": CALENDAR_ID,
"merchantId": YOUR_MERCHANT_ID,
"staffId": YOUR_STAFF_ID,
"start": "2023-11-11T15:00:00Z",
"end": "2023-11-12T16:00:00Z",
"type": "Appointment",
"bookingId": "BOOKING_ID"
}
],
"bookings": [
{
"bookingId": "BOOKING_ID",
"merchantId": YOUR_MERCHANT_ID,
"bookingMethod": "Appointment",
"status": "Approved",
"isCompleted": true,
"startsOn": "2023-11-11T15:00:00Z",
"totalClientTimespan": {
"start": "2023-11-11T15:00:00Z",
"end": "2023-11-11T16:00:00Z",
"duration": 60
},
"staffId": YOUR_STAFF_ID,
"staffFirstName": "STAFF_FIRST_NAME",
"staffLastName": "STAFF_LAST_NAME",
"items": [
{
"serviceId": YOUR_SERVICE_ID,
"serviceName": "Request an Appointment",
"price": {
"visibility": "Show",
"amount": "0.00",
"amountPerPerson": "0.00",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "None"
},
"reservedClientTimespan": {
"start": "2023-11-11T15:00:00Z",
"end": "2023-11-11T16:00:00Z",
"duration": 60
},
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
],
"location": "Business",
"locationText": "",
"payment": {
"total": "0.00",
"paid": "0.00",
"onlinePaymentStatus": "None"
},
"createdOn": "2023-10-25T13:16:50Z",
"createdBy": "Client",
"modifiedOn": "2023-11-11T17:49:07Z",
"modifiedBy": "Staff",
"modifiedByStaffId": YOUR_STAFF_ID,
"isScheduled": true,
"clientCount": 1,
"client": {
"id": 9278135,
"firstName": "CLIENT_FIRST_NAME",
"lastName": "CLIENT_LAST_NAME",
"email": "CLIENT_EMAIL",
"homePhoneNumber": "",
"mobilePhoneNumber": "",
"presence": "Arrived",
"remindByEmail": true,
"remindBySMS": false,
"additionalRequest": ""
},
"quickNote": ""
}
]
}For multi-service appointments, the query’s response will list each service as an individual calendar event, each event leading back to the same appointment (same bookingId) as seen in the sample below.
{
"calendarEvents": [
{
"id": 13567800,
"merchantId": YOUR_MERCHANT_ID,
"staffId": YOUR_STAFF_ID,
"start": "2023-11-15T14:00:00Z",
"end": "2023-11-15T15:00:00Z",
"type": "Appointment",
"bookingId": "A10021380"
},
{
"id": 13567801,
"merchantId": YOUR_MERCHANT_ID,
"staffId": YOUR_STAFF_ID,
"start": "2023-11-15T15:00:00Z",
"end": "2023-11-15T16:00:00Z",
"type": "Appointment",
"bookingId": "A10021380"
}
],
"bookings": [
{
"bookingId": "A10021380",
"merchantId": YOUR_MERCHANT_ID,
"bookingMethod": "Appointment",
"status": "Approved",
"isCompleted": false,
"startsOn": "2023-11-15T14:00:00Z",
"totalClientTimespan": {
"start": "2023-11-15T14:00:00Z",
"end": "2023-11-15T16:00:00Z",
"duration": 120
},
"staffId": 21750,
"staffFirstName": "STAFF_FIRST_NAME",
"staffLastName": "STAFF_LAST_NAME",
"items": [
{
"serviceId": 154023,
"serviceName": "SERVICE_NAME",
"price": {},
"reservedClientTimespan": {
"start": "2023-11-15T14:00:00Z",
"end": "2023-11-15T15:00:00Z",
"duration": 60
},
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
},
{
"serviceId": 98453,
"serviceName": "SERVICE_NAME",
"price": {},
"reservedClientTimespan": {
"start": "2023-11-15T15:00:00Z",
"end": "2023-11-15T16:00:00Z",
"duration": 60
},
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
],
"location": "Business",
"locationText": "",
"payment": {
"total": "0.00",
"paid": "0.00",
"onlinePaymentStatus": "None"
},
"createdOn": "2023-11-15T00:00:10Z",
"createdBy": "Client",
"modifiedOn": "2023-11-15T00:00:11Z",
"modifiedBy": "Client",
"isScheduled": true,
"clientCount": 1,
"client": {
"id": 9278135,
"firstName": "CLIENT_FIRST_NAME",
"lastName": "CLIENT_LAST_NAME",
"email": "CLIENT_EMAIL",
"homePhoneNumber": "CLIENT_HOME_PHONE",
"mobilePhoneNumber": "CLIENT_MOBILE_PHONE",
"presence": "Arrived",
"remindByEmail": true,
"remindBySMS": false,
"additionalRequest": ""
},
"quickNote": ""
}
]
}
Limitations
This API shall not be used to generate reports or export data.
The starting date of a query cannot be more than 7 days in the past.