API Documentation

Options for back-end integration

The SuperSaaS system is backed by a database that stores information about your clients, their appointments, and your settings. SuperSaaS provides APIs (Application Programming Interfaces) to facilitate integration with your back end systems so that you can extend our system to provide custom functionality.

Currently two parts of the database are exposed via APIs:

  1. User database API. (Read, Update and Write). If your site has its own login system and database with user information you can sync it with the SuperSaaS user database. This allows you to provide your users with a way to register and log in only once.
  2. Appointment database API. (Mostly Read Only). You can retrieve appointment information organized by schedule or by user and filtered by date. See the rest of this page for details.

Accessing the Appointment Database

The APIs can be used to retrieve appointment information from the database. Only some of the APIs support writing, and not yet for all schedule types. In particular, the service schedule does not support writing, and on a capacity schedule appointments can be created but not empty slots.

Three ways to do Authentication

The API supports several different 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 header, and optionally protect the connection with SSL. However you cannot, of course, put your account password in the HTML code when accessing the API from a client browser, because that would reveal your password to someone looking at the source of the page.

To facilitate calling the APIs from a client side script you can authenticate with a MD5 hash instead of sending your account password. The hash is calculated from a concatenated string that includes your account name, the user name and your account password. 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

You can obtain an XML document with recent changes to the schedule by sending a HTTP GET request to the server. The request should be formatted as follows:

http://www.supersaas.com/api/changes/<schedule_id>.xml?from=<last_retrieval>&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 last number on the URL
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 the checksum or basic HTTP authentication 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 an XML document that lists all appointments that have seen a change of any kind since the "last retrieval" time.

<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>
   <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 whether or not 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 the deleted field is set to true)
created_by
updated_by
Name of the creator / updater. Blank if 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 API

The "recent changes" API requires polling the SuperSaaS server at intervals to see if anything changed. If you want to keep a back-end system updated with changes made on a SuperSaaS schedule there are several options.

The Agenda API

This API allows you to retrieve the appointments of a single user in XML format. Authentication can be done with a one-way hash to allow retrieval from a client-side AJAX request. Output fields are identical to those listed above.

http://www.supersaas.com/api/agenda/<schedule_id>.xml?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 last number on the URL. If omitted shows all schedules, you need to add an "account" parameter in that case (see below).
userEither the user's name or the user's ID or zero to get the bookings for the administrator.
from(Optional) If present only return bookings after 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 too. You can also omit this field and use the checksum or basic HTTP authentication instead.
checksumAn MD5 hash containing the account name, password and user name. Ignored if you send the account 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 all schedules will be listed. For example, this would show all appointments for a user for each schedule in the account:

http://www.supersaas.com/api/agenda.xml?user=<user_id>&password=<admin_password>&account=<account_name>

All input values need to be URL encoded. The system will reply with an XML document that lists all appointments occurring after the "from" time. The output fields are identical to those for the "recent changes" API.

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

The Availability API

This API allows you to retrieve a list of free spaces in XML format.

http://www.supersaas.com/api/free/<schedule_id>.xml?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 last number on the URL.
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 too. You can also omit this field and use the checksum or basic HTTP authentication instead.
checksum
user
An MD5 Hash containing the account name, password and user name. Ignored if you send the 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 "Not Modified" response does not take this into account. The system will reply with an XML document that lists all free spaces occurring after the "from" time.

<slots>
   <slot start="2014-01-18 13:00:00" finish="2014-01-18 15:00:00">
      ...
   </slot>
   <slot slot start="2014-01-18 15:00:00" finish="2014-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 schedule 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.

Read, Create, Update and Delete Appointments

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

POST /api/bookings

The request should either contain an XML document describing the new user, or have the fields as URI encoded parameters. See the end of the document for the format. 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.xml If you want to update the booking via the API later then you need to extract the ID (1234) of the created object from this URL. The response will be a 404 ("Not Found") if the schedule doesn't exist and a 403 ("Not authorized") if the password or checksum is incorrect. If the object did not pass validation, for example due to an invalid e-mail address, then status 422 ("Unprocessable Entity") will be returned, with the body of the response containing the error messages.

Read one appointment

GET /api/bookings/{id}.xml?schedule_id={schedule_id}
If the booking exists and the authorization is correct then the response will be a 200 ("OK") with the response body containing an XML document describing the appointment.
<booking>
   ...
</booking>

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

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?schedule_id=123&start=2014-10-10&limit=1".

Update an appointment

PUT /api/bookings/{id}.xml
The system looks for the record with the given ID and updates it. Similar to the "create" API you can either provide an XML document or URI encoded parameters. The result will be an empty response with a 200 ("OK") or a 404 ("Not Found") if the ID is not found, perhaps because the appointment has been deleted. If the object contains invalid fields the response will be a 422 ("Unprocessable Entity") with an 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

DELETE /api/bookings/{id}.xml
The system will look for the ID in the database and return a 200 ("OK") if the record was deleted successfully, or a 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 also do a POST with the extra parameter "_method=DELETE"

Data Format

The fields that you can supply are determined by the settings on the configuration screen, "Process" tab. This screen also determines which values are optional, and which mandatory. Note that in XML messages the underscores are replaced with dashes.

FieldComment
schedule_idThe ID of the schedule. You can obtain this number by looking at the Configure Overview page, it is the last number on the URL.
password, checksum(Optional) See above, you can optionally pass one or both of these parameters as part of the authentication process
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 e-mail address of the user. Ignored if you use the e-mail 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.

When reading data the retrieved XML document will contain the following fields in addition to the ones listed above:
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

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)

http://www.supersaas.com/api/bookings?schedule_id=123&password=secret&booking[start]=2014-10-10 12:00&booking[finish]=2014-10-10 12:00&booking[full_name]=Test

Back to Tutorial index