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

      How to Make a Booking With a Survey Using the API

      This document provides examples on how to use the Booxi booking API with survey answers.

      Creating a New Appointment

      A new booking can be created by simply making a POST /booking using data as shown below.

      {
         "merchantId": YOUR_MERCHANT_ID,
         "bookingMethod": "Appointment",
         "startsOn": "2000-01-01T12:00:00Z",
         "status": "Approved",
         "staffId": YOUR_STAFF_ID,
         "items":
         [
            {
               "serviceId": YOUR_SERVICE_ID
            }
         ],
         "client":
         {
            "firstName": "Mike",
            "lastName": "Abbott",
            "email": "mike.abbott@domain.com"
         }
      }

      Creating an Appointment or Reservation With Survey Answers

      The example below assumes that your webpage is displaying a survey using surveyjs.io or a compatible service. Your survey data should be formatted as shown below. The property surveyModel can be found in the “service” object as each service can be assigned a survey. 


      For more information about the “service” object, please consult the booking API OpenAPI definition under the section “schema”.

      "surveyModel":
      {
         "pages": 
         [
            {
               "name": "default",
               "elements": 
               [
                  {
                     "name": "_question1",
                     "type": "checkbox",
                     "title": "YOUR_QUESTION",
                     "choices": ["ANSWER 1","ANSWER 2","ANSWER 3","ANSWER 4"],
                     "isRequired": false
                  }
               ]
            }
         ]
      }

      Once a survey has been filled out, surveyjs.io will provide the answers in a JSON object. 

       

      To create a new booking and include its survey answers, it is necessary to make a POST /booking with your data structured as shown below. Be mindful that data is structured differently for an appointment than it is for a group reservation.


      Appointment Booking

      For an “Appointment”, answers must be assigned to their respective items[].surveyAnswers and so for each service provided during that said appointment.


      The example below showcases a “multi service” appointment with their sets of answers.

      {
         "merchantId": 001,
         "bookingMethod": "Appointment",
         "startsOn": "2022-02-20T16:00:00Z",
         "status": "Approved",
         "staffId": 001,
         "items":
         [
            {
               "serviceId": 1000,
               "serviceName": "Service 1",
               "price": {},
               "reservedClientTimespan": {},
               "duration": 30,
               "spacingAfter": 0,
               "isBusySpacingAfter": true
               "surveyAnswers": {"_question1":["ANSWER 2"]}
            },
            {
               "serviceId": 1001,
               "serviceName": "Assembly",
               "price": {},
               "reservedClientTimespan": {},
               "duration": 30,
               "spacingAfter": 15,
               "isBusySpacingAfter": false
               "surveyAnswers": {"_question1":["ANSWER 4"]}
            }
        ],
        "client":
        {
           "firstName": "Mike",
           "lastName": "Abbott",
           "email": "mike.abbott@domain.com",
        }
      }

      Group Reservation Booking

      In the case of a group reservation, answers must be assigned to attendees[].surveyAnswers and so for each attendee of that reservation.


      The below showcases a reservation with two attendees each with their respective survey answers.

      {
         "merchantId": YOUR_MERCHANT_ID,
         "bookingMethod": "GroupReservation",
         "groupEventId": YOUR_GROUP_EVENT_ID,
         "client":
         {
            "firstName": "Mike",
            "lastName": "Abbott",
            "email": "mike.abbott@domain.com",
            "isAttending": true
         },
         "attendees":
         [
            {
               "firstName": "Mike",
               "lastName": "Abbott",
               "email": "mike.abbott@domain.com",
               "isRequester": true,
               "surveyAnswers": {"_question1":["ANSWER 1"]}
            },
            {
               "firstName": "Laura",
               "lastName": "Flynn",
               "email": "laura.flynn@domain.com",
               "isRequester": false,
               "surveyAnswers": {"_question1":["ANSWER 3"]}
            }
        ],
        "clientCommunication": "ClientAndAttendees",
        "createdBy": "Client"
      }

      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.