POST /availability/search
Search for available time slots or ranges for a set of services.
Permissions & Security
A Merchant API key is required.
The Merchant API key provided must be valid.
Requirements
The merchantId provided must be valid and associated with an active store.
The serviceId provided must be valid (and not deleted), and be associated with the merchantId.
Request body example
{
"searchMode": "verbose",
"merchantId": 34497,
"range": {
"startsOn": "2026-03-19T09:00:00-05:00",
"endsOn": "2026-03-19T11:00:00-05:00"
},
"bookingItems": [
{
"serviceId": 173269
},
{
"serviceId": 198246
}
],
"onlyIncludeStaffs": [74144]
}Request URL for North America
https://api.booxi.com/booking/v1/availability/search
Request URL for Europe
https://api.booxi.eu/booking/v1/availability/search
cURL
curl -X 'POST' \
'https://api.booxi.com/booking/v1/availability/search' \
-H 'accept: application/json' \
-H 'Booxi-APIKey: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"searchMode": "verbose",
"merchantId": 34497,
"range": {
"startsOn": "2026-03-19T09:00:00-05:00",
"endsOn": "2026-03-19T11:00:00-05:00"
},
"bookingItems": [
{
"serviceId": 173269
},
{
"serviceId": 198246
}
],
"onlyIncludeStaffs": [74144]
}'
Successful Response
Here’s an example of a successful response.
{
"availability": {
"timeSelectionMode": "TimeSlot",
"bookingTimeSlots": [
{
"startsOn": "2026-03-19T14:00:00Z",
"staffSelectionMode": "Disabled",
"staffIds": [
74144
],
"items": [
{
"serviceId": 173269,
"duration": 30,
"spacingAfter": 0,
"isBusySpacingAfter": true
},
{
"serviceId": 198246,
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
]
},
{
"startsOn": "2026-03-19T14:15:00Z",
"staffSelectionMode": "Disabled",
"staffIds": [
74144
],
"items": [
{
"serviceId": 173269,
"duration": 30,
"spacingAfter": 0,
"isBusySpacingAfter": true
},
{
"serviceId": 198246,
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
]
},
{
"startsOn": "2026-03-19T14:30:00Z",
"staffSelectionMode": "Disabled",
"staffIds": [
74144
],
"items": [
{
"serviceId": 173269,
"duration": 30,
"spacingAfter": 0,
"isBusySpacingAfter": true
},
{
"serviceId": 198246,
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
]
},
{
"startsOn": "2026-03-19T14:45:00Z",
"staffSelectionMode": "Disabled",
"staffIds": [
74144
],
"items": [
{
"serviceId": 173269,
"duration": 30,
"spacingAfter": 0,
"isBusySpacingAfter": true
},
{
"serviceId": 198246,
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
]
},
{
"startsOn": "2026-03-19T15:00:00Z",
"staffSelectionMode": "Disabled",
"staffIds": [
74144
],
"items": [
{
"serviceId": 173269,
"duration": 30,
"spacingAfter": 0,
"isBusySpacingAfter": true
},
{
"serviceId": 198246,
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
]
},
{
"startsOn": "2026-03-19T15:15:00Z",
"staffSelectionMode": "Disabled",
"staffIds": [
74144
],
"items": [
{
"serviceId": 173269,
"duration": 30,
"spacingAfter": 0,
"isBusySpacingAfter": true
},
{
"serviceId": 198246,
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
]
},
{
"startsOn": "2026-03-19T15:30:00Z",
"staffSelectionMode": "Disabled",
"staffIds": [
74144
],
"items": [
{
"serviceId": 173269,
"duration": 30,
"spacingAfter": 0,
"isBusySpacingAfter": true
},
{
"serviceId": 198246,
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
]
},
{
"startsOn": "2026-03-19T15:45:00Z",
"staffSelectionMode": "Disabled",
"staffIds": [
74144
],
"items": [
{
"serviceId": 173269,
"duration": 30,
"spacingAfter": 0,
"isBusySpacingAfter": true
},
{
"serviceId": 198246,
"duration": 60,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
]
}
]
},
"staffs": [
{
"id": 74144,
"name": "Jim Smith",
"firstName": "Jim",
"lastName": "Smith",
"position": "Owner",
"biography": "",
"profileImageUrl": "",
"timeSelectionMode": "ServiceTimeSelection"
}
],
"services": [
{
"id": 173269,
"merchantId": 34497,
"name": "Consultation",
"tags": "",
"duration": 30,
"showDuration": true,
"hasDurationCustomization": false,
"bookingMethod": "Appointment",
"location": "Business",
"locationText": "",
"price": {
"visibility": "Show",
"amount": "0.00",
"amountPerPerson": "0.00",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "None"
},
"hasPriceCustomization": false,
"categoryId": 0,
"categoryName": "Main Services",
"description": "",
"profileImageUrl": "",
"staffSelectionMode": "Disabled",
"timeSelectionMode": "TimeSlot",
"bookingPolicy": "Any modification or cancellation must be done at least 24 hours before the appointment time.",
"instructions": ""
},
{
"id": 198246,
"merchantId": 34497,
"name": "Heather Myers",
"tags": "",
"duration": 60,
"showDuration": true,
"hasDurationCustomization": false,
"bookingMethod": "Appointment",
"location": "Business",
"locationText": "",
"price": {
"visibility": "Show",
"amount": "0.00",
"amountPerPerson": "0.00",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "None"
},
"hasPriceCustomization": false,
"categoryId": 0,
"categoryName": "Main Services",
"description": "",
"profileImageUrl": "",
"staffSelectionMode": "Disabled",
"timeSelectionMode": "TimeSlot",
"bookingPolicy": "Any modification or cancellation must be done at least 1 min before the appointment time.",
"instructions": ""
}
]
}You can test this endpoint at the following links.
For North America | For Europe |
Notes and Limitations
If entering more than one service, note that certain conditions must be met.
A maximum of 5 services can be entered in the request body.
A maximum of 1 staff ID can be entered for
onlyIncludeStaffs.The response can return "noAvailabilityReason"; this is generated in the following cases:
One of the services is offline.
One of the services' “Enable Online Booking” setting is disabled.
One of the staff members' “Enable Online Booking” setting is disabled.
One of the staff members is offline.
The entered services do not have the same location.
The entered staff is not assigned to one of the entered services.
The entered services have no common resource.
You may use the response to create a booking using the POST
/booking endpoint; if you do, be aware of the "noAvailabilityReason" mentioned above.
The following booking limits are ignored (i.e. they are not enforced):
Limit time before
Limit time in advance
To receive the next page of results, generate a new request using only the cursor key (obtained from your response). Example request body:
{
"cursor": "csa_eJxzNjI01TUyNjU2MTAzNTY0sDAyMjI2MTIyMzQ1NjY1NjcyNjU2NjIyNjU2NjUyNjYxNjU2NjI2NjU2NjYyNjU2NjI2MTM0NTU2"
}