How to Create a Booking Using the API

Learn about the POST /Booking endpoint.

You can create a new appointment or reservation type booking by using the POST /booking endpoint. Please take note that this endpoint requires a partner API Key. If you haven’t been provided with such a key, please contact your Booxi representative.

Be reminded that the URL at which you access the API depends on your hosting region. This article presents examples from a North American hosting.

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. Take note that the client must be associated with your merchant or part of a shared clientele.

Mandatory Parameters

Optional Parameters

 

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

 

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.

---

References 

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