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:
You can create a new appointment or reservation type booking by using the POST /booking endpoint.
Creating a New Booking
To create a new booking using the POST /booking endpoint, your request must minimally include a merchant Id, a booking method, a starting date, a status, a staff id, a service id and the client’s first and last name and email address. If the client the booking is created for already exists, you can use its client id instead of name and email address. Note that the client must be associated with your merchant or be part of a shared clientele.
Mandatory Parameters
Parameter | Format | Description |
merchantId | integer merchantId=9999 | Merchant the booking is created for. |
bookingMethod | string bookingMethod=Appointment | Type of booking to create. Supported types are:
|
startsOn | string startsOn=2023-01-01T00:00:00Z | Date and time on which the booking starts. Must be in RFC3339 format, UTC time. |
status | string status=Approved | Status assigned to the booking. Only “Approved” is supported at this time. |
staffId | integer staffId=786 | ID of the staff assigned to the booking. |
items | array items=[{serviceId=1000}] | List of services to be provided during the booking. |
client | string client={John, Doe, OR integer client={id=100} | Client’s first and last name, as well as email address.
ID of the client the booking is made for, only if the client already exists. |
Optional Parameters
Parameter | Format | Description |
language | string language=eng | The language the content should be provided in. |
createdBy | string createdBy=Staff | Who created the booking? If omitted, it will default to “Staff”. Possible values are “Staff” or “Client”. |
acquisitionChannel | string acquisitionChannel=e-commerce | The booking's acquisition channel (defined by the business) passed during booking creation. Specifications:
|
location | string location=Business | The location at which the service will be provided. Options depend on the service type. For appointments, options include:
For group reservations, options include:
|
Request URL for North America
https://api.booxi.com/booking/v1/booking
cURL using a Client’s Name and eMail Address
curl -X POST
"https://api.booxi.com/booking/v1/booking?language:eng"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
-d "{\"merchantId\":YOUR_MERCHANT_ID,\"bookingMethod\":\"Appointment\",
\"startsOn\":\"STARTING_DATE\",\"status\":\"Approved\",\"staffId\":YOUR_STAFF_ID,
\"items\":[{\"serviceId\":YOUR_SERVICE_ID}],\"client\":{\"firstName\":\"FIRST_NAME\",
\"lastName\":\"LAST_NAME\",\"email\":\"EMAIL\"},\"createdBy\":\"Staff\"}"
Request Body using a Client’s Name and eMail Address
{
"merchantId": YOUR_MERCHANT_ID,
"bookingMethod": "Appointment",
"acquisitionChannel": "e-commerce",
"startsOn": "2023-01-01T00:00:00Z",
"status": "Approved",
"staffId": YOUR_STAFF_ID,
"items": [
{
"serviceId": YOUR_SERVICE_ID
}
],
"client": {
"firstName": "FIRST_NAME",
"lastName": "LAST_NAME",
"email": "EMAIL"
},
"createdBy": "Staff"
}
cURL using a client ID
curl -X POST
"https://api.booxi.com/booking/v1/booking?language:eng"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
-d "{\"merchantId\":YOUR_MERCHANT_ID,\"bookingMethod\":\"Appointment\",
\"startsOn\":\"STARTING_DATE\",\"status\":\"Approved\",\"staffId\":YOUR_STAFF_ID,
\"items\":[{\"serviceId\":YOUR_SERVICE_ID}],\"client\":{\"id\":YOUR_CLIENT_ID}}"
Request Body using a client ID
{
"merchantId": YOUR_MERCHANT_ID,
"bookingMethod": "Appointment",
"startsOn": "2023-01-01T00:00:00Z",
"status": "Approved",
"staffId": YOUR_STAFF_ID,
"items": [
{
"serviceId": YOUR_SERVICE_ID
}
],
"client": {
"id": YOUR_CLIENT_ID
},
"createdBy":"Staff"
}
Additional Rules
When creating an appointment to be serviced “at home”, if a client’s address is missing in its client record, the street address will be updated with the information provided in the request body. Note that the country and state/province will not be updated.
To prevent the creation of a booking for a blocked client, you must set rules=”ClientBlocked”. To allow such a booking, you must set both rules=”ClientBlocked” and ignoreError=”ClientStatus”.
Testing POST /Booking
You can test this endpoint at the following links.
For North America | For Europe |
In the section “Request body”, from the dropdown menu select the type of booking you wish to test. Examples are provided for the following uses cases:
Appointment with a single service
Appointment with multiple services
Appointment booking using client ID (instead of name)
Appointment with online payment
Reservation where the client is attending
Reservation where the client isn’t attending
Successful JSON Response
When the query is successful, the response will include the booking ID, details about the service(s) provided, the merchant location, the client record and the payment (if applicable).
Here’s an example of a successful response:
{
"bookingId": "BOOKING_ID",
"merchantId": YOUR_MERCHANT_D,
"bookingMethod": "Appointment",
"status": "Approved",
"isCompleted": false,
"acquisitionChannel": "e-commerce",
"startsOn": "STARTING_DATE",
"totalClientTimespan": {
"start": "STARTING_TIME",
"end": "ENDING_TIME",
"duration": 30
},
"staffId": YOUR_STAFF_ID,
"items": [
{
"serviceId": "YOUR_SERVICE_ID",
"serviceName": "SERVICE_NAME",
"resourceId": "YOUR_RESOURCE_ID",
"resourceName": "YOUR_RESOURCE_NAME",
"serviceHasAssociatedResources": true,
"price": {
"visibility": "Show",
"amount": "0.00",
"amountPerPerson": "0.00",
"amountPerHour": "0.00",
"currency": "CURRENCY",
"isStartingAt": false,
"tax": "None"
},
"reservedClientTimespan": {
"start": "STARTING_TIME",
"end": "ENDING_TIME",
"duration": 00
},
"duration": 00,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
],
"location": "LOCATION",
"locationText": "",
"client": {
"id": YOUR_CLIENT_NAME,
"firstName": "CLIENT_FIRST_NAME",
"lastName": "CLIENT_LAST_NAME",
"email": "CLIENT_EMAIL_ADDRESS",
"homePhoneNumber": "CLIENT_PHONE_NUMBER",
"mobilePhoneNumber": CLIENT_MOBILE_NUMBER"",
"presence": "Expecting",
"remindByEmail": false,
"remindBySMS": false,
"additionalRequest": ""
},
"payment": {
"total": "0.00",
"paid": "0.00",
"onlinePaymentStatus": "None"
},
"createdOn": "CREATION_DATE",
"createdBy": "Staff",
"createdByStaffId": "YOUR_STAFF_ID",
"modifiedOn": "MODIFICATION_DATE",
"modifiedBy": "Staff",
"modifiedByStaffId": "YOUR_STAFF_ID",
"isScheduled": true,
"clientCount": 1
}Limitations
It is not possible to create an appointment using a client ID if the client doesn’t already exist.
In the request body, if a reminder by SMS is requested without providing a mobile phone number, the request will fail (error code 400 - invalid request).
In the request body, if a reminder by email is requested without providing an email address, the request will fail (error code 400 - invalid request).
In the request body, if a service provided “at home” is requested without providing an address, the request will fail (error code 400 - invalid request).
If a request is made for a client entry that has been merged, deleted or anonymized, the request will fail (error code 400 - invalid request).
The authentication method requires a secure environment.
The endpoint must not be exposed on a webpage but rather server side.