The SuperSaaS system is backed by a database that stores information about your users, 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:
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.
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:
$user = 'user_name@client.com';$checksum = md5("Your_account_nameYour_account_password$user")checksum = Digest::MD5.hexdigest("Your_account_nameYour_account_password#{'user_name@client.com'}")
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>
| Parameter | Value | ||
|---|---|---|---|
| schedule_id | The 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 | ||
| from | The time since the last retrieval in the format "YYYY-MM-DD HH:MM:SS" in UTC | ||
| password | The administrator password for the account the schedule belongs too. You can also omit this field and use the checksum or basic HTTP authentication instead. | ||
| slot | 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 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 slots=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>
| Parameter | Value | ||
|---|---|---|---|
| id | A unique booking identifier that can be used to match it against earlier downloads | ||
| resource | If your schedule contains more than one resource this is the resource that the user selected (resource only) | ||
| slot | Information about the slot this booking belongs to (capacity only) | ||
| service | Contains a service identifier (service only) | ||
| start | Start time in the format "YYYY-MM-DD HH:MM:SS" in the local time zone | ||
| finish | Finish time in the format "YYYY-MM-DD HH:MM:SS" in the local time zone | ||
| deleted | true or false depending whether or not this booking has been deleted | ||
| created_on | Creation time in the format "YYYY-MM-DD HH:MM:SS" in UTC (note: not local) | ||
| updated_on | Last 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 | User name of the creator / updater. Blank if an anonymous booking or a system change such as a PayPal status update | ||
| waitlisted | If 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.
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.
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>
| Parameter | Value | ||
|---|---|---|---|
| schedule_id | The 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). | ||
| user | Either 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 | ||
| password | The 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 | An MD5 hash containing the account name, password and user name. Ignored if you send the account password. | ||
| slots | When you add the parameter "slots=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>
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>
| Parameter | Value | ||
|---|---|---|---|
| schedule_id | The 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. | ||
| from | Only return free spaces later than this time. Should be in the format "YYYY-MM-DD HH:MM:SS" in local time. | ||
| password | The 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) | ||
| 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="2012-01-18 13:00:00" finish="2012-01-18 15:00:00">
...
</slot>
<slot slot start="2012-01-18 15:00:00" finish="2012-01-18 18:00:00">
...
</slot>
</slots>
| Parameter | Value | ||
|---|---|---|---|
| slot | Contains 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 | ||
| title | The title of the slot, contains an id property that can be used to match it to other slots | ||
| description | Description of the slot if available (capacity schedule only) | ||
| location | Location of the slot if available (capacity schedule only) | ||
| count | Specifies 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.
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.
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.
GET /api/bookings/{id}.xml?schedule_id={schedule_id}
<booking> ... </booking>
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=2012-10-10&limit=1".
PUT /api/bookings/{id}.xml
DELETE /api/bookings/{id}.xml
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.
| Field | Comment | ||
|---|---|---|---|
| schedule_id | The 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. | ||
| Field | Comment | ||
|---|---|---|---|
| id | The internal ID assigned to this appointment that you can use to update the appointment | ||
| created-on | The time this appointment was created in UTC | ||
| updated-on | The time this appointment was last modified in UTC | ||
| created-by, updated-by, user-id | The name and ID of the user who created/updated the appointment if available | ||
| status | Status message of the payment or the approval process, if applicable | ||
| price | Price charged for the appointment, if applicable | ||
| res-name | (Resource schedule only) Name of the resource this booking belongs to | ||
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)
Back to Tutorial index