Use Cases
      Back to home
      1. Knowledge Base
      2. Webhooks & APIs
      3. Use Cases

      How to Build a Custom Booking Process Using the API

      Please take note that the endpoints used in this article might require 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.

      North America Europe
      api.booxi.com api.booxi.eu

       

      The following article will guide you through the process of building a custom booking experience using the Booxi API.

       

      To complete this task, we will follow these simple steps:

      • Display information about your store
      • Create a dropdown list of services you offer
      • Create a dropdown list of your staff members
      • Display availabilities of a selected service
      • Create a “Book Now” button

      Display a Store’s Information

      First, let’s start by populating the web page with information about your store location. The information stored in the Booxi database can be retrieved by sending a request to the API with a call to GET /merchant per the details shown below.

       

      Request URL

      https://api.booxi.com/booking/v1/merchant

       

      cURL

      curl -X GET 
      "https://api.booxi.com/booking/v1/merchant" 
      -H  "accept: application/json"

       

      If your request is valid, the API’s response will include data formatted as a JSON object. With that information now on hand, display whatever you judge pertinent such as your business name, group, address and phone number.

       

      Testing GET /Merchant

      You can test this endpoint at the links below:

      For North America For Europe
      getMerchant getMerchant

       

      Here’s an example of a successful JSON response.

      {
         "id": 1,
         "name": "YOUR_SHOPS_NAME",
         "isAvailableOnline": true,
         "storeNumber": "US...",
         "groupId": 001,
         "groupName": "YOUR_STORES_GROUP_NAME",
         "groupCategoryId": 1,
         "groupCategoryName": "YOUR_GROUP_CATEGORY",
         "address": {},
         "contactFirstName": "Mike",
         "contactLastName": "Abbott",
         "phoneNumber": "+1222333444",
         "email": "mike.abbott@domain.com",
         "tags": "YOUR_TAGS",
         "websiteUrl": "",
         "bookingUrl": "...",
         "apiKey": "YOUR_API_KEY",
         "description": "...",
         "coverImageUrl": "https://...",
         "profileImageUrl": "https://...",
         "currency": "USD",
         "tax1Name": "",
         "tax1Rate": "0.0",
         "tax2Name": "",
         "tax2Rate": "0",
         "timeZone": "America/New_York",
         "latitude": "",
         "longitude": "",
         "defaultLanguage": "eng",
         "openHours": [{}]
      }

       

      Display Services

      Next, let’s build a list of services your business provides.  To do so, we will send  the API a request and fill a drop down menu with the result. Your request can be customized by specifying what booking method the request should be limited to, Appointment, GroupReservation or Rental.

      Furthermore, If your business is providing a substantial amount of services, successive requests can be made to construct a multi-page list by supplying the request with an offset (starting index) and a limit (item count).

      Whatever your options are, send a request to the API by making a call to GET /service per the below details.

       

      Request URL

      https://api.booxi.com/booking/v1/service

       

      cURL

      curl -X GET 
      "https://api.booxi.com/booking/v1/service?bookingMethod=Appointment&offset=0&limit=20"
       
      -H  "accept: application/json"

       

      Testing GET /Service

      You can test this endpoint at the links below:

      For North America For Europe
      findService findService

       

      If your request is valid, the API’s response will include data formatted as a JSON object. What that data, fill in the drop down menu or any UI element you opted for.

       

      Here’s an example of a successful JSON response.

      {
         "offset": 0,
         "limit": 20,
         "total": 5,
         "items":
         [
            {
               "id": 1,
               "merchantId": 1,
               "name": "YOUR_SERVICES_NAME",
               "tags": "TOUR_TAGS",
               "duration": 30,
               "showDuration": true,
               "hasDurationCustomization": false,
               "bookingMethod": "Appointment",
               "location": "Business",
               "locationText": "",
               "price": {},
               "hasPriceCustomization": false,
               "categoryId": 0,
               "categoryName": "YOUR_SERVICE_CATEGORY",
               "description": "...",
               "profileImageUrl": "https://...",
               "staffSelectionMode": "AssignedStaff",
               "timeSelectionMode": "TimeSlot",
               "maxReservationSize": 0,
               "bookingPolicy": "...",
               "instructions": "...",
               "metadata":
               {
                  "referenceId": "102"
               }
            }
         ]
      }

       

      Display Staff

      Similarly as services, your web page could include a staff drop down menu.  Once again, we can do so by sending the API a request and filling a drop down menu with the result. You can supplement your request by assigning a serviceId and limit results to the staff members providing the said service. The parameters “offset” and “limit” are also available should you need to build a multi-page list.

       

      To retrieve a list of all staff members,  make a call to GET /staff as shown below.

       

      Request URL

      https://api.booxi.com/booking/v1/staff

       

      cURL

      curl -X GET 
      "https://api.booxi.com/booking/v1/service?bookingMethod=Appointment&offset=0&limit=20"
      -H  "accept: application/json" 

       

      Testing GET /Staff

      You can test this endpoint at the links below:

      For North America For Europe
      findStaff findStaff

       

      If your request is valid, the API’s response will include data formatted as a JSON object. With that data, fill in the drop down menu or any UI element you opted for. Take note that once a staff member is selected , the list of services can be updated by sending a new request with GET /service and using the selected staff’s ID and,  vice-versa if a service is selected first.

       

      Here’s an example of a successful JSON response.

      {
         "offset": 0,
         "limit": 20,
         "total": 4,
         "items":
         [
            {
               "id": 1,
               "name": "Jane Poe",
               "firstName": "Jane",
               "lastName": "Poe",
               "position": "Manager",
               "biography": "The friendly manager...",
               "profileImageUrl": "https://...",
               "timeSelectionMode": "ServiceTimeSelection"
            }
         ]
      }

       

      Display Availabilities

      With a valid serviceId we can now query the API about a service’s availability and build a calendar or list of time slots. Your request must minimally include a serviceId, a start and end date (in RFC3339 format) . Other optional parameters are available.

       

      To retrieve any service’s availability, make a call to GET /service/{serviceId}/availability as shown below.

       

      Request URL

      https://api.booxi.com/booking/v1/service/00001/availability

       

      cURL

      curl -X GET 
      "https://api.booxi.com/booking/v1/service/00001/availability?from=START_DATE&to=END_DATE"
      -H  "accept: application/json"

       

      Testing GET /Service/{serviceId}/Availability

      You can test this endpoint at the links below:

      For North America For Europe
      getServiceAvailability getServiceAvailability

       

      Here’s an example of a successful JSON response.

      {
        "cursor": null,
        "serviceAvailability": [
          {
            "start": "2023-01-01T00:00:00Z",
            "end": "2023-01-10T01:00:00Z",
            "serviceId": YOUR_SERVICE_ID,
            "staffId": YOUR_STAFF_ID,
            "groupEventId": YOUR_GROUP_EVENT_ID,
            "capacity": 3,
            "placesLeft": 1
          },
          {
            "start": "2023-01-28T00:00:00Z",
            "end": "2023-01-28T01:00:00Z",
            "serviceId": YOUR_SERVICE_ID,
            "staffId": YOUR_STAFF_ID,
            "groupEventId": YOUR_GROUP_EVENT_ID,
            "capacity": 3,
            "placesLeft": 2
          }
        ],
        "staffSelectionMode": "AssignedStaff",
        "timeSelectionMode": "GroupEvent"
      }

       

      Make a Booking

      Once a client has made a choice of service, staff and time slot, we can create a booking by making a call to POST /booking. If the booking is made for a new client, it is mandatory to provide the client's first and last name as well as an email address. For a returning client, a Booxi client ID will suffice (see details below).

       

      Request URL

      https://api.booxi.com/booking/v1/booking

       

      cURL for a New Client

      curl -X POST 
      "https://api.booxi.com/booking/v1/booking?rules=None" 

      -H  "accept: application/json" 
      -H  "Content-Type: application/json" 

      -d "{\"merchantId\":YOUR_MERCHANT_ID,\"bookingMethod\":\"Appointment\",
      \"startsOn\":\"2022-01-25T9:00:00Z\",\"status\":\"Approved\",\"staffId\":YOUR_STAFF_ID,
      \"items\":[{\"serviceId\":YOUR_SERVICE_ID}],\"client\":{\"firstName\":\"FIRST_NAME\",
      \"lastName\":\"LAST_NAME\",\"email\":\"EMAIL\"}}"

       

      Request Body for a New Client

      {
         "merchantId": 1,
         "bookingMethod": "Appointment",
         "startsOn": "2022-01-25T9:00:00Z",
         "status": "Approved",
         "staffId": 1,
         "items":
         [
            {
               "serviceId": 1
            }
         ],
         "client": 
         {
           "firstName": "Emilie",
           "lastName": "Authier",
           "email": "emilie.authier@booxi.com"
         }
      }

       

      cURL for a Returning Client

      curl -X POST 
      "https://api.booxi.com/booking/v1/booking?rules=None" 

      -H  "accept: application/json" 
      -H  "Content-Type: application/json" 

      -d "{\"merchantId\":YOUR_MERCHANT_ID,\"bookingMethod\":\"Appointment\",
      \"startsOn\":\"2022-01-25T9:00:00Z\",\"status\":\"Approved\",\"staffId\":YOUR_STAFF_ID,
      \"items\":[{\"serviceId\":YOUR_SERVICE_ID}],\"client\":{\"id\":\"YOUR_CLIENT_ID\"}}"

       

      Request Body for a Returning Client

      {
        "merchantId": 1,
        "bookingMethod": "Appointment",
        "startsOn": "2022-01-25T9:00:00Z",
        "status": "Approved",
        "staffId": 1,
        "items":
      [
         {
           "serviceId": 1
         }
        ],
        "client": 
        {
         "id": YOUR_CLIENT_ID,
        }
      }

       

      Testing POST /Booking

      You can test this endpoint at the link below:

      For North America For Europe
      createBooking createBooking

       

      Once the booking is successfully completed, the API will send a response as a JSON object which contains all details related to your booking.

       

      Here’s an example of a successful response.

      {
         "bookingId": "A00006500",
         "merchantId": 1002,
         "bookingMethod": "Appointment",
         "status": "Approved",
         "isCompleted": false,
         "startsOn": "2021-02-20T16:00:00Z",
         "totalClientTimespan":
         {
            "start": "2021-02-20T16:00:00Z",
            "end": "2021-02-20T16:30:00Z",
            "duration": 30
         },
         "staffId": 582,
         "items":
         [
            {
               "serviceId": 1000,
               "serviceName": "Self Printing",
               "price": {},      
               "reservedClientTimespan": {},
               "duration": 23,
               "spacingAfter": 0,
               "isBusySpacingAfter": true
            }
        ],
        "location": "Business",
        "locationText": "",
        "client":
        {
           "firstName": "Emilie",
           "lastName": "Authier",
           "email": "emilie.authier@booxi.com",
           "homePhoneNumber": "",
           "mobilePhoneNumber": "",
           "presence": "Expecting",
           "remindByEmail": false,
           "remindBySMS": false,
           "additionalRequest": ""
         },
         "payment":
         {
            "total": "5.00",
            "paid": "0.00",
            "onlinePaymentStatus": "None"
         },
         "createdOn": "2021-02-17T20:10:38Z",
         "createdBy": "Staff",
         "modifiedOn": "2021-02-17T20:10:38Z",
         "modifiedBy": "Staff",
         "isScheduled": true,
         "clientCount": 1
      }

       

      References

      For more information about the API and its usage, refer to the following links:

      Where can API keys be found:

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