Appointment API

Besides calls to read or update appointments, this API provides methods to retrieve a subset of recent changes, or to retrieve availability information of a schedule. Note that not all schedule types support all methods. Five API endpoints are available to retrieve and manipulate appointment information:

1. Recent Changes – /api/changes – List changes since a specified date
2. List Appointments – /api/range – List appointments in a time range
3. Agenda – /api/agenda – Retrieve the appointments of a single user
4. Availability – /api/free – Retrieve a list of free spaces
5. Appointments – /api/bookings – Create, read, update and delete appointments

The API accepts data as URL parameters, as JSON or as XML, and can return data as either JSON or XML.

Authentication

You typically include your API key with each request, as a header or a parameter, but you can also authenticate via a checksum. Please refer to the Authentication page for details.

The Recent Changes API

All input values need to be URL encoded. The system will respond with a list of all appointments that have seen a change recently, or since the time specified by the from parameter.

{
  "bookings": [
    {
      "id": "123456",
      ...
    }
  ]
}

<bookings>
   <booking>
      ...
   </booking>
   <booking>
      ...
   </booking>
</bookings>

If you include the parameter slot=true on a request for a capacity-type schedule, the document will be formatted as a tree of slots containing the relevant bookings:

{
  "slots": [
    {
      ...
      "bookings": [
        {
          "id": "123456",
          ...
        }
      ]
    }
  ]
}

<slots>
   <slot>
      ...
      <bookings>
         <booking>
            ...
         </booking>
         <booking>
            ...
         </booking>
      </bookings>
   </slot>
   <slot>
      ...
   </slot>
</slots>

All times are returned in the format YYYY-MM-DD HH:MM:SS, irrespective of the account settings. Start and finish time use the time zone for the calendar, the created_on and updated_on fields are in UTC.

Alternatives to using the Recent Changes API

Instead of frequently polling our server to see if anything changed it is preferable to configure a webhook. The webhook can actually be configured to supply every change as a payload so it may make polling entirely unnecessary. If you want to keep a back-end system updated with changes made on a SuperSaaS schedule, there are several alternative options.

• You can use the webcal interface. This is an RFC 2445 compliant interface for which several client libraries exist. However, the iCalendar format allows only limited details about an appointment to be transmitted.
• You can send an email (or SMS) notification to yourself and extract the relevant values from those messages. This requires setting up an automatic email reader.
• You can publish your schedule to Google Calendar and use Google’s extensive API to query it.

The List Appointments API

All input values need to be URL encoded. For Resource and Service schedules, the system will respond with a list of appointments in the requested range.

{
  "bookings": [
    {
      "id": "123456",
      ...
    }
  ]
}

<bookings>
   <booking>
      ...
   </booking>
   <booking>
      ...
   </booking>
</bookings>

If you specify a “capacity”-type schedule, the system will respond with a list of slots in the requested range.

{
  "slots": [
    {
      "id": "123456",
      ...
    }
  ]
}

<slots>
   <slot>
      ...
   </slot>
   <slot>
      ...
   </slot>
</slots>

If you include the parameter slot=true in the request for a capacity-type schedule, the bookings inside the slots will be included:

{
  "slots": [
    {
      ...
      "bookings": [
        {
          "id": "123456",
          ...
        }
      ]
    }
  ]
}

<slots>
   <slot>
      ...
      <bookings>
         <booking>
            ...
         </booking>
         <booking>
            ...
         </booking>
      </bookings>
   </slot>
   <slot>
      ...
   </slot>
</slots>

All times returned by the API are in the ISO format YYYY-MM-DD HH:MM:SS, irrespective of the account settings. Start and finish time use the time zone for the calendar, the created_on and updated_on fields are in UTC.

The Agenda API

The Agenda API allows you to retrieve the appointments for a single user. Authentication can be done with a one-way hash to allow retrieval through a client-side AJAX request. Output fields are identical to those listed for the Recent Changes API.

If you omit the schedule_id parameter, appointments for all schedules in the account will be listed. In that case, however, you need to add an account parameter to specify the name of the account for which you want to retrieve the appointments.

For example, the following call would show all appointments for a user for each schedule in the account:

All input values need to be URL encoded. The system will reply with a document that lists all appointments occurring after the from time. The output fields are identical to those for the Recent Changes API.

{
  "bookings": [
    {
      "id": "123456",
      ...
    },
    {
      "id": "789123",
      ...
    }
  ]
}

<bookings>
   <booking>
      ...
   </booking>
   <booking>
      ...
   </booking>
</bookings>

The Availability API

The Availability API allows you to retrieve a list of free spaces in a specific schedule. Note that this API does not support “Service”-type schedules (because that schedule type calculates the available space in the browser).

It is recommended that you add an If-Modified-Since header to reduce server load. This will result in a 304 Not Modified response if nothing changed since your last request. Note that the number of free spots can also change due to the time passing, for example, because a schedule does not allow appointments to be made in the past. The 304 Not Modified response does not take this into account. The system will reply with a document that lists all free spaces occurring after the from time.

{
  "slots": [
    {
      "start": "2024-01-18T13:00:00",
      "finish": "2024-01-18T15:00:00",
      ...
    },
    {
      "start": "2024-01-18T15:00:00",
      "finish": "2024-01-18T18:00:00",
      ...
    }
  ]
}

<slots>
   <slot start="2024-01-18 13:00:00" finish="2024-01-18 15:00:00">
      ...
   </slot>
   <slot start="2024-01-18 15:00:00" finish="2024-01-18 18:00:00">
      ...
   </slot>
</slots>

All times are returned in the time zone for the account, and in the format YYYY-MM-DD HH:MM:SS, irrespective of the format in the account settings.

The Appointments API

The Appointments API allows you to create, read, update and delete appointments from a schedule. Note that it doesn’t support service schedules and while you can create new appointments inside slots in a capacity schedule, it is not possible to create empty slots through the API.

Create a new appointment

To create a new appointment, you need to send an HTTP POST request to /api/bookings.json (or .xml). The request should either contain a JSON or an XML document describing the new user, or have the fields as URI encoded parameters. See the table below for an explanation of the fields.

<?xml version="1.0"?>
<booking>
   <start>...</start>
   <finish>...</finish>
   <full-name>Full Name</full-name>
</booking>

{
  "booking": {
    "start": "…",
    "finish": "…",
    "full_name": "Full Name"
  }
}

If the booking was created correctly, the response will be a header with status code 201 Created. The Location field of the response header will contain the URL that you can use to update the appointment later, e.g.: Location: https://www.supersaas.com/api/bookings/1234.json.xml. If you want to update the booking via the API later, then you need to extract the ID of the created object (1234) from this URL. The response will be 404 Not Found if the schedule doesn’t exist and 403 Not authorized if the api_key or checksum is incorrect. If the object did not pass validation, for example due to an invalid email address, then status 422 Unprocessable Entity will be returned, with the body of the response containing the error messages.

Data Format

The fields that you can supply are determined on the Configure > Process tab. These settings also determine which values are optional, and which required. Note that in XML messages, the underscores are replaced with dashes.

Illustrative Usage

Resource Schedule

To create an appointment in the resource schedule with ID <schedule_id>, you would send the following HTTP POST request (the values still need to be URI encoded):

Appointments can also be created by sending a JSON request. The authentication and schedule ID are encoded in the URL and the appointment data in the JSON body. The example below will have the same effect as the example above with URL-encoded parameters.

{
  "start": "YYYY-MM-DD HH:MM:SS",
  "finish": "YYYY-MM-DD HH:MM:SS",
  "full_name": "Test"
}

Capacity Schedule

To create an appointment in the capacity schedule with ID <schedule_id>, you would send the following HTTP POST request (the values still need to be URI encoded):

Appointments can also be created by sending a JSON request. The authentication and schedule ID are encoded in the URL and the appointment data in the JSON body. The example below will have the same effect as the example above with URL-encoded parameters.

{
  "slot_id": "slot_id",
  "full_name": "Test"
}

Read a single appointment

If the booking exists and the authorization is correct, then the response will be 200 OK with the response body containing a JSONan XML document describing the appointment.

<booking>
   ...
</booking>

{
  "id": "123456",
  ...
}

When reading data, the retrieved document will contain the following fields in addition to the ones listed above:

Read multiple appointments

There are three specialized APIs available to retrieve multiple appointments depending on whether you want those filtered by user, by date, or by recent changes. See the beginning of this section for details. In addition to those, you can retrieve all appointments for a calendar with:

You can pass the limit=X parameter to limit the number of returned results to X. As a special case, on a resource or service type schedule you can pass a start and/or finish parameter to limit results to that time window. This allows you to retrieve the next upcoming appointment with a request like /api/bookings.json?schedule_id=123&start=2024-10-10&limit=1.

Show forms

When a form is attached to an appointment, you can show the form’s data by adding the form=true parameter to the URL. The output will be the same as that of the Form API.

Update an appointment

To update an appointment, send an HTTP PUT request to /api/bookings.json, and specify the ID of the appointment in question. Similar to creating an appointment, you can either provide a JSONan XML document or use URI encoded parameters.

The system looks for the record with the given ID and updates it. The result will be an empty response with a 200 OK status. However, if the ID is not found, for example because the appointment has already been deleted, a 404 Not Found status code is returned. Furthermore, if the object contains invalid fields the response will be a 422 Unprocessable Entity with a JSONan XML error document.

Delete an appointment

Deleting an appointment can be done by sending an HTTP DELETE request to /api/bookings.json, specifying the ID of the appointment in question.

The system will look for the ID in the database and return 200 OK if the record was deleted successfully or 404 Not found if it (no longer) exists.