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

      How to Use the GET/calendar API Endpoint

      The following article will explain how to use the GET/calendar API endpoint to retrieve entries in a staff’s calendar and present a few of its applications.

      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.

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

      Use Cases

      Here are a few use cases where the GET/calendar API endpoint is used in practical applications.

      Staff Calendar Application

      Fetch all entries from a staff’s calendar and present the results in an interface or application accessible by the staff so as to provide a summary of upcoming events.

      Custom Clienteling Application

      Fetch all bookings for a specific date and staff member, display results in a clienteling application so clients can visualize their preferred staff’s availability.


      Fetching Events From a Staff’s Calendar

      To fetch the content of a staff’s calendar, use the GET /calendar endpoint as per the details below. Your request must minimally include a start and end date, a valid staff ID, the type of events to fetch and the referenced objects to include in the response.

      Mandatory Parameters

      Parameter Format Description
      from from=date
      from=2023-11-11T09%3A00%3A00Z      		 Query’s starting date, in RFC3339 format. The starting date is inclusive. This parameter is required when the cursor is null.
      to to=date
      to=2023-11-12T09%3A00%3A00Z      		 Query’s ending date, in RFC3339 format. The ending date is also inclusive. This parameter is required when the cursor is null.
      staffId staffId=ID
      staffId=21750      		 The ID associated with the staff the query is made for. Required when the cursor is null.
      eventType eventType=type
      eventType=Appointment      		 The event type to fetch. Supported types are “Appointment”, “GroupEvent” and “TimeSlot”. This parameter is required when the cursor is null. The parameter must be repeated in the query for each type to fetch.
      include include=type
      include=Appointment      		 The type of events. Supported values: Appointment only. Required when the cursor is null. The parameter must be repeated for each type to include.

       

      Optional Parameters

      Parameter Format Description
      language language=lng
      language=eng

      ISO 639-3 except for french which use “fre”. The API also accepts 639-1 and code 639-2. Consult the swagger for more details about its format.      		 The language code that the content should be in. Consult the swagger for more details about what language is supported.
      cursor cursor=string
      cursor=sl_eJxjZGALcmVgYGdQTtj      		 A token to get the next set of results. When the cursor is set, all other query parameters should NOT be set.

       

      Limitations

      • Starting date cannot be more than 7 days in the past.

       

      Request URL for the North America

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

      cURL

      curl -X GET "https://api.booxi.com/booking/v1/calendar?from=2023-11-11T09%3A00%3A00Z&to=2023-11-12T09%3A00%3A00Z&staffId=YOUR_STAFF_ID&eventType=Appointment&include=Appointment" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

       

      Request URL for Europe

      https://api.booxi.eu/booking/v1/calendar

      cURL

      curl -X GET "https://api.booxi.eu/booking/v1/calendar?from=2023-11-11T09%3A00%3A00Z&to=2023-11-12T09%3A00%3A00Z&staffId=YOUR_STAFF_ID&eventType=Appointment&include=Appointment" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

       

      You can test this API at the following links.

      For North America For Europe
      listCalendar listCalendar

      Successful JSON Response

      When the query is successful, the response will include all calendar entries associated with the specified staff, for the specified type, for the range of time provided.

      Here’s an example of a successful response:

      {
        "calendarEvents": [
          {
            "id": CALENDAR_ID,
            "merchantId": YOUR_MERCHANT_ID,
            "staffId": YOUR_STAFF_ID,
            "start": "2023-11-11T15:00:00Z",
            "end": "2023-11-12T16:00:00Z",
            "type": "Appointment",
            "bookingId": "BOOKING_ID"
          }
        ],
        "bookings": [
          {
            "bookingId": "BOOKING_ID",
            "merchantId": YOUR_MERCHANT_ID,
            "bookingMethod": "Appointment",
            "status": "Approved",
            "isCompleted": true,
            "startsOn": "2023-11-11T15:00:00Z",
            "totalClientTimespan": {
              "start": "2023-11-11T15:00:00Z",
              "end": "2023-11-11T16:00:00Z",
              "duration": 60
            },
            "staffId": YOUR_STAFF_ID,
            "staffFirstName": "STAFF_FIRST_NAME",
            "staffLastName": "STAFF_LAST_NAME",
            "items": [
              {
                "serviceId": YOUR_SERVICE_ID,
                "serviceName": "Request an Appointment",
                "price": {
                  "visibility": "Show",
                  "amount": "0.00",
                  "amountPerPerson": "0.00",
                  "amountPerHour": "0.00",
                  "currency": "CAD",
                  "isStartingAt": false,
                  "tax": "None"
                },
                "reservedClientTimespan": {
                  "start": "2023-11-11T15:00:00Z",
                  "end": "2023-11-11T16:00:00Z",
                  "duration": 60
                },
                "duration": 60,
                "spacingAfter": 0,
                "isBusySpacingAfter": true
              }
            ],
            "location": "Business",
            "locationText": "",
            "payment": {
              "total": "0.00",
              "paid": "0.00",
              "onlinePaymentStatus": "None"
            },
            "createdOn": "2023-10-25T13:16:50Z",
            "createdBy": "Client",
            "modifiedOn": "2023-11-11T17:49:07Z",
            "modifiedBy": "Staff",
            "modifiedByStaffId": YOUR_STAFF_ID,
            "isScheduled": true,
            "clientCount": 1,
            "client": {
              "id": 9278135,
              "firstName": "CLIENT_FIRST_NAME",
              "lastName": "CLIENT_LAST_NAME",
              "email": "CLIENT_EMAIL",
              "homePhoneNumber": "",
              "mobilePhoneNumber": "",
              "presence": "Arrived",
              "remindByEmail": true,
              "remindBySMS": false,
              "additionalRequest": ""
            },
            "quickNote": ""
          }
        ]
      }

      Important Note

      For multi-service appointments, the query’s response will list each service as an individual calendar event, each event leading back to the same appointment (same bookingId) as seen in the sample below.

      {
        "calendarEvents": [
          {
            "id": 13567800,
            "merchantId": YOUR_MERCHANT_ID,
            "staffId": YOUR_STAFF_ID,
            "start": "2023-11-15T14:00:00Z",
            "end": "2023-11-15T15:00:00Z",
            "type": "Appointment",
            "bookingId": "A10021380"
          },
          {
            "id": 13567801,
            "merchantId": YOUR_MERCHANT_ID,
            "staffId": YOUR_STAFF_ID,
            "start": "2023-11-15T15:00:00Z",
            "end": "2023-11-15T16:00:00Z",
            "type": "Appointment",
            "bookingId": "A10021380"
          }
        ],
        "bookings": [
          {
            "bookingId": "A10021380",
            "merchantId": YOUR_MERCHANT_ID,
            "bookingMethod": "Appointment",
            "status": "Approved",
            "isCompleted": false,
            "startsOn": "2023-11-15T14:00:00Z",
            "totalClientTimespan": {
              "start": "2023-11-15T14:00:00Z",
              "end": "2023-11-15T16:00:00Z",
              "duration": 120
            },
            "staffId": 21750,
            "staffFirstName": "STAFF_FIRST_NAME",
            "staffLastName": "STAFF_LAST_NAME",
            "items": [
              {
                "serviceId": 154023,
                "serviceName": "SERVICE_NAME",
                "price": {},
                "reservedClientTimespan": {
                  "start": "2023-11-15T14:00:00Z",
                  "end": "2023-11-15T15:00:00Z",
                  "duration": 60
                },
                "duration": 60,
                "spacingAfter": 0,
                "isBusySpacingAfter": true
                }
              },
              {
                "serviceId": 98453,
                "serviceName": "SERVICE_NAME",
                "price": {},
                "reservedClientTimespan": {
                  "start": "2023-11-15T15:00:00Z",
                  "end": "2023-11-15T16:00:00Z",
                  "duration": 60
                },
                "duration": 60,
                "spacingAfter": 0,
                "isBusySpacingAfter": true
              }
            ],
            "location": "Business",
            "locationText": "",
            "payment": {
              "total": "0.00",
              "paid": "0.00",
              "onlinePaymentStatus": "None"
            },
            "createdOn": "2023-11-15T00:00:10Z",
            "createdBy": "Client",
            "modifiedOn": "2023-11-15T00:00:11Z",
            "modifiedBy": "Client",
            "isScheduled": true,
            "clientCount": 1,
            "client": {
              "id": 9278135,
              "firstName": "CLIENT_FIRST_NAME",
              "lastName": "CLIENT_LAST_NAME",
              "email": "CLIENT_EMAIL",
              "homePhoneNumber": "CLIENT_HOME_PHONE",
              "mobilePhoneNumber": "CLIENT_MOBILE_PHONE",
              "presence": "Arrived",
              "remindByEmail": true,
              "remindBySMS": false,
              "additionalRequest": ""
            },
            "quickNote": ""
          }
        ]
      }

      Limitations

      • This API shall not be used to generate reports or export data.
      • The starting date of a query cannot be more than 7 days in the past.

      References

      For more information about the Booxi APIs and their usage, please refer to the following links:

      Europe: https://api.booxi.eu/doc/booking.html

      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.