Back to index
Developer documentation

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 the API is under development and not all schedule types support all methods yet. Four 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

Please refer to the Authentication Page.

The Recent Changes API

Using the Recent Changes API, you can obtain a document with all changes to a particular schedule since the date specified in the request. The request should be formatted as follows:
Try it out
https://www.supersaas.com/api/changes/<schedule_id>.jsonxml?from=<last_retrieval>&api_key=your_api_key
This tutorial can display code snippets relevant to your account if you log in
This tutorial can display code snippets relevant to your account if you generate an API Key at the bottom of the Account Info page by clicking the Generate button.
Input Values
ParameterValue
schedule_idThe ID of the schedule you want to download. You can obtain this by looking at the Configure Overview page, it’s the number at the end of the URL in your browser’s address bar
from(Optional) Only retrieve changes made after this time. If omitted shows the most recent changes. Use the ISO format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS in UTC
to(Optional) Only retrieve changes made before this time. Use the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS in UTC
api_keyThe administrator API Key for the account the schedule belongs too. You can also omit this field and use HTTP Basic Authentication or an MD5 hash instead.
limit(Optional) Indicate the maximum number of results you want returned. For large requests you can make multiple requests and add an offset parameter to page through the results
user(Optional) Either the user’s name or ID or foreign key. Limit the output to bookings for this user. Use user=0 to get the bookings for the administrator
slot(Optional) When you add the parameter slot=true, then additional information about the relevant slots will be included with the bookings (capacity type only)

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 have included the parameter slot=true on the 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>
Output Fields
ParameterValue
idA unique booking identifier that can be used to match it against earlier downloads
resourceres_nameIf your schedule contains more than one resource, this is the resource that was selected (resource only)
resource_idThe ID of the resource that was selected (resource and JSON only)
slot_idInformation about the slot this booking belongs to (capacity only)
service_nameContains a service identifier (service only)
service_idThe ID of the service that was selected (service and JSON only)
startStart time in the format YYYY-MM-DD HH:MM:SS in the local time zone
finishFinish time in the format YYYY-MM-DD HH:MM:SS in the local time zone
deletedtrue or false, depending on whether this booking has been deleted
created_onCreation time in the format YYYY-MM-DD HH:MM:SS in UTC (Note: not local)
updated_onLast changed time in the format YYYY-MM-DD HH:MM:SS in UTC (This will be the deletion time if deleted is set to true)
created_by
updated_by
user_id
Name and ID of the creator/updater. Blank in case of an anonymous booking or a system change, such as a PayPal status update
waitlistedIf this booking is waitlisted, this field contains the letter W (capacity only)
<more>Additional fields as selected in the Process Configuration screen

All times are returned in the format YYYY-MM-DD HH:MM:SS, independent of the format specified in the account settings.

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 availability data for your schedule to Google Calendar and use their extensive API to query it.

List Appointments

This API allows you to retrieve all appointments or slots from a schedule within a time range. The request should be formatted as follows:
Try it out
https://www.supersaas.com/api/range/<schedule_id>.jsonxml?api_key=your_api_key
Input Values
ParameterValue
schedule_idThe ID of the schedule you want to download. You can obtain this by looking at the Configure Overview page, it’s the number at the end of the URL in your browser’s address bar
from(Optional) Only retrieve appointments starting on or after this time. If omitted uses the current time. Use the ISO format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS in the local time of the calendar
to(Optional) Only retrieve appointments starting before this time. Use the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS in local time
today(Optional) If you add the parameter today=true then the API will set to and from to the current day in the local time zone
api_keyThe administrator API Key for the account the schedule belongs too. You can also omit this field and use HTTP Basic Authentication or an MD5 hash instead
limit(Optional) Indicate the maximum number of results you want returned. For large requests you can make multiple requests and add an offset parameter to page through the results
slot(Optional) If you add the parameter slot=true then additional information about the relevant bookings will be included with the slots (capacity type only)
user(Optional) Either the user’s name or ID or foreign key. Limit the output to bookings for this user. Use user=0 to get the bookings for the administrator (resource and service type only)
resource_id
service_id
(Optional) If one of these parameters is present only appointments with the specific resource_id or service_id will be returned (resource and service type only)

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 specified 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 on the request for a capacity-type schedule, the bookings for the slots will also be inserted:

{
  "slots": [
    {
      ...
      "bookings": [
        {
          "id": "123456",
          ...
        }
      ]
    }
  ]
}
<slots>
   <slot>
      ...
      <bookings>
         <booking>
            ...
         </booking>
         <booking>
            ...
         </booking>
      </bookings>
   </slot>
   <slot>
      ...
   </slot>
</slots>
Output Fields
ParameterValue
idA unique booking identifier that can be used to match it against earlier downloads
resourceres_nameIf your schedule contains more than one resource, this is the resource that was selected (resource only)
resource_idThe ID of the resource that was selected (resource and JSON only)
slot_idInformation about the slot this booking belongs to (capacity only)
service_nameContains a service identifier (service only)
service_idThe ID of the service that was selected (service and JSON only)
startStart time in the format YYYY-MM-DD HH:MM:SS in the local time zone
finishFinish time in the format YYYY-MM-DD HH:MM:SS in the local time zone
created_onCreation time in the format YYYY-MM-DD HH:MM:SS in UTC (Note: not local)
updated_onLast changed time in the format YYYY-MM-DD HH:MM:SS in UTC
created_by
updated_by
user_id
Name and ID of the creator/updater. Blank in case of an anonymous booking or a system change, such as a PayPal status update
waitlistedIf this booking is waitlisted, this field contains the letter W (capacity only)
<more>Additional fields as selected in the Process Configuration screen

All times returned by the API are in the ISO format YYYY-MM-DD HH:MM:SS, independent of the format specified in the account settings.

The Agenda API

This API allows you to retrieve the appointments of 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.

Try it out
https://www.supersaas.com/api/agenda/<schedule_id>.jsonxml?user=<user_id>&api_key=<admin_api_key>&from=<last_retrieval>
Input Values
ParameterValue
schedule_idThe number of the schedule you want to download. You can obtain this number by looking at the Configure Overview page. It is the number at the end of the URL in your browser’s address bar.

When omitted, all schedules are shown. In this case, however, you need to add an account parameter instead (see example below).
userEither the user’s name or ID. Use user=0 to get the bookings for the administrator.
from(Optional) If present, only bookings after this time are returned. Should be in the format YYYY-MM-DD HH:MM:SS or YYYY-MM-DD in local time
api_keyThe administrator API Key for the account the schedule belongs to. You can also omit this field and use HTTP Basic Authentication or an MD5 hash instead.
checksumAn MD5 hash containing the account name, API key and username. Ignored if you send the account API Key via api_key.
slotWhen you add the parameter slot=true, then additional information about the relevant slots will be included with the bookings (capacity type only)

If you omit the schedule_id parameter, all schedules 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:

Try it out
https://www.supersaas.com/api/agenda.jsonxml?user=<user_id>&api_key=<admin_api_key>&account=&from=<last_retrieval>

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

This API allows you to retrieve a list of free spaces in a specific schedule. Note that this API does not support “Service”-type schedules.

Try it out
https://www.supersaas.com/api/free/<schedule_id>.jsonxml?from=<from_time>&api_key=your_api_key
Input Values
ParameterValue
schedule_idThe number of the schedule you want to download. You can obtain this number by looking at the Configure Overview page. It is the number at the end of the URL in your browser’s address bar
fromOnly return free spaces later than this time. Should be in the format YYYY-MM-DD HH:MM:SS in local time.
api_keyThe administrator API Key for the account the schedule belongs to. You can also omit this field and use HTTP Basic Authentication or an MD5 hash instead.
checksum
user
An MD5 Hash containing the account name, account api_key and username. Ignored if you send the account API Key via api_key. You can use a random value for the username.
length(Optional) Limit the search for free spaces of at least this length in minutes. The default length is used if this parameter is not present. (resource schedule only)
resource(Optional) Limit the search for free spaces to the named resource. (resource schedule only)
full(Optional) Set to true to return full slots as well as empty slots. (capacity schedule only)
maxresults(Optional) Limit the number of returned results. Default is 10.

It is recommended that you add a 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>
Output Fields
ParameterValue
slotContains the properties start and finish that specify the beginning and end of the slot in the format YYYY-MM-DD HH:MM:SS in local time. The finish property can be empty if a slot extends indefinitely
titleThe title of the slot, contains an ID property that can be used to match it to other slots
descriptionDescription of the slot if available (capacity schedule only)
locationLocation of the slot if available (capacity schedule only)
countSpecifies how many places are available in this slot. For resource type schedules, this will always be 1. Will be 0 for slots marked as having no capacity limit.

All times are returned in local time and in the format YYYY-MM-DD HH:MM:SS, independent of the format specified in the account settings.

Note that this API is under development and not all schedule types support all methods yet.

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 in a capacity schedule, it is not possible to create empty slots through the API.

Currently, all API actions are performed as administrator, creating or updating as a regular user is not yet supported. You can use the checksum authentication mentioned above if you want to create an appointment from a client-side script inside a browser.

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.

POST /api/bookings.json

If the record has been 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.

Input Values
FieldComment
schedule_idThe ID of the schedule. You can obtain this number by looking at the Configure Overview page. It is the number at the end of the URL in your browser’s address bar
api_key, checksum(Optional) See above, you can optionally pass one or both of these parameters as part of the authentication process
user_id(Optional) The booking will be created “on behalf” of this user if a user_id is supplied. The user_id can be either the ID returned when creating the user, or it can have the format 1234fk if you passed in a foreign key when creating the user
booking[start],
booking[finish]
(Resource schedule only) Start and end time for the appointment in local time
booking[slot_id](Capacity schedule only) The ID of the slot for which you want to create the appointment
booking[resource_id](Resource schedule only, optional) If the schedule has more than one resource you can indicate which one. If you don’t know the ID you can pass the name instead
booking[full_name,
address, mobile, phone]
If any of these attributes are present they are stored unchanged as UTF-8 encoded strings
booking[country]Either not present or a two character ISO 3166-1 country code
booking[email]The email address of the user. Ignored if you use the email address as login name.
booking[field_1,field_2,
field_1_r,field_2_r,
super_field]
The values of the two custom fields on the user object, the two custom fields on the appointment and the supervisor field, irrespective of the display label you have given them in the user interface.
form(Optional) Adding form=true will add an attached form to the output. The format is identical to that produced by the Form API.
webhook(Optional) If webhook=true is present it will trigger any webhooks connected to the schedule.

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):

Try it out
https://www.supersaas.com/api/bookings.json?schedule_id=<schedule_id>&api_key=your_api_key&booking[start]=start time&booking[finish]=finish time&booking[full_name]=Test

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.

https://www.supersaas.com/api/bookings.json?schedule_id=<schedule_id>&api_key=secret
{
  "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):

Try it out
https://www.supersaas.com/api/bookings.json?schedule_id=<schedule_id>&api_key=your_api_key&booking[slot_id]=slot_id&booking[full_name]=Test

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.

https://www.supersaas.com/api/bookings.json?schedule_id=<schedule_id>&api_key=secret
{
  "slot_id": "slot_id",
  "full_name": "Test"
}

Read a single appointment

GET /api/bookings/{id}.jsonxml?schedule_id={schedule_id}
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:

Output Fields
FieldComment
idThe internal ID assigned to this appointment that you can use to update the appointment
created_onThe time this appointment was created in UTC
updated_onThe time this appointment was last modified in UTC
created_by,
updated_by,
user_id
The name and ID of the PERSON who created/updated the appointment if available
statusStatus message of the payment or the approval process, if applicable
pricePrice charged for the appointment, if applicable
res_name(Resource schedule only) Name of the resource this booking belongs to

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:

GET /api/bookings.json

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 the Form API.

Update an appointment

To update an appointment, you need to send an HTTP PUT request to /api/bookings.json, specifying 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.

PUT /api/bookings/{id}.json.xml?schedule_id={schedule ID}

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.

If the software you are using does not support sending of the HTTP PUT verb, then you can simply do a regular POST instead.

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.

DELETE /api/bookings/{id}.json.xml?schedule_id={schedule ID}

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.

If the software you are using is not able to send the HTTP DELETE verb, then you can send an HTTP POST request with the extra parameter _method=DELETE instead.