Documentation
Print page

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/api/changes – List changes since a specified date
  2. Agenda/api/agenda – Retrieve the appointments of a single user
  3. Availability/api/free – Retrieve a list of free spaces
  4. 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.

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

API Authentication

The APIs support several types of authentication. For server-to-server communication, you can send your account name and password as URL parameters or in an HTTP Basic Authentication (BA) header. If you are sending the password in clear text it’s a good idea to access the API over an SSL (https) encrypted connection. Including the account password in a call should never be done when accessing the API from a client browser as it would reveal your password to anyone looking at the HTML source of the page.

Hence, to facilitate calling the APIs from a client-side script, you should authenticate with an MD5 hash instead. The hash is calculated from a concatenated string that includes your account name, account password and the user name. Since it includes the account password, which is only known to you and SuperSaaS, it cannot be calculated by anyone else. Because the checksum includes the visitor’s name, it is different for every visitor and you can safely put it in an AJAX call to be performed by the browser. Most languages provide an easy way to calculate an MD5 hash, for example:

PHP: $user = 'user_name@client.com';$checksum = md5("Your_account_nameYour_account_password$user")
Ruby: checksum = Digest::MD5.hexdigest("Your_account_nameYour_account_password#{'user_name@client.com'}")

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
No schedules found,
showing placeholder data
http://www.supersaas.com/api/changes/<schedule_id>.jsonxml?from=<last_retrieval>&password=<admin_password>
This tutorial can display code snippets relevant to your account if you log in.
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
fromThe time since the last retrieval in the format YYYY-MM-DD HH:MM:SS in UTC
passwordThe administrator password for the account the schedule belongs too. You can also omit this field and use HTTP Basic Authentication or an MD5 hash instead.
slotWhen 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 reply with a document that lists all appointments that have seen a change of any kind 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
resourceIf your schedule contains more than one resource, this is the resource that was selected (resource only)
slotInformation about the slot this booking belongs to (capacity only)
serviceContains a service identifier (service 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
Name 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 ical 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.

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
No schedules found,
showing placeholder data
http://www.supersaas.com/api/agenda/<schedule_id>.jsonxml?user=<user_id>&password=<admin_password>
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 in local time
passwordThe administrator password 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, account password and user name (see API Authentication). Ignored if you send the account password via password.
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
http://www.supersaas.com/api/agenda.jsonxml?user=<user_id>&password=<admin_password>&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

This API allows you to retrieve a list of free spaces in a specific schedule.

Try it out
No schedules found,
showing placeholder data
http://www.supersaas.com/api/free/<schedule_id>.jsonxml?from=<from_time>&password=<admin_password>
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.
passwordThe administrator password 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 password and user name. Ignored if you send the account password via password. You can use a random value for the user name.
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": "2016-01-18T13:00:00",
      "finish": "2016-01-18T15:00:00",
      ...
    },
    {
      "start": "2016-01-18T15:00:00",
      "finish": "2016-01-18T18:00:00",
      ...
    }
  ]
}
<slots>
   <slot start="2016-01-18 13:00:00" finish="2016-01-18 15:00:00">
      ...
   </slot>
   <slot start="2016-01-18 15:00:00" finish="2016-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.

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: http://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 password 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 mandatory. 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
password, 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.

Illustrative Usage

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

Try it out
No schedules found,
showing placeholder data
http://www.supersaas.com/api/bookings.json?schedule_id=123&password=secret&booking[start]=start time&booking[finish]=finish time&booking[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 type schedule you can pass a start parameter to only show results past that time. This allows you to retrieve the next upcoming appointment with a request like /api/bookings.json?schedule_id=123&start=2016-10-10&limit=1.

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

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

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.