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. These API endpoints are available to retrieve and manipulate appointment information:
- Recent Changes –
/api/changes
– List changes since a specified date - List Appointments –
/api/range
– List appointments in a time range - Agenda –
/api/agenda
– Retrieve the appointments of a single user - Availability –
/api/free
– Retrieve a list of free spaces - 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
https://www.supersaas.com/api/changes/<schedule_id>.jsonxml?from=<last_retrieval>&api_key=your_api_key
Parameter | Value |
---|---|
schedule_id | The 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 ten 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_key | The 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 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>
Parameter | Value |
---|---|
id | A unique booking identifier that can be used to match it against earlier downloads |
resource res_name | If your schedule contains more than one resource, this is the resource that was selected (resource only) |
resource_id | The ID of the resource that was selected (resource and JSON only) |
slot_id | Information about the slot this booking belongs to (capacity only) |
service _name | Contains a service identifier (service only) |
service_id | The ID of the service that was selected (service and JSON 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 on whether 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 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 |
waitlisted | If this booking is waitlisted, this field contains the letter W (capacity only) |
<more> | Additional fields as selected on the Configure > Process tab |
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
If you want to keep a back-end system updated with changes made on a SuperSaaS schedule, there are several alternative options:
- 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.
- You can publish your schedule to a Google Calendar and use Google’s extensive API to query it.
- 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.
The List Appointments API
https://www.supersaas.com/api/range/<schedule_id>.jsonxml?api_key=your_api_key
Parameter | Value |
---|---|
schedule_id | The 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_key | The 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 or service type only) |
resource_id | (Optional) If one of these parameters is present only appointments with the specific resource_id or service_id will be returned (resource or 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 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>
Parameter | Value |
---|---|
id | A unique booking identifier that can be used to match it against earlier downloads |
resource res_name | If your schedule contains more than one resource, this is the resource that was selected (resource only) |
resource_id | The ID of the resource that was selected (resource and JSON only) |
slot_id | Information about the slot this booking belongs to (capacity only) |
service _name | Contains a service identifier (service only) |
service_id | The ID of the service that was selected (service and JSON 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 |
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 |
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 |
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 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. You can optionally do authentication with a one-way hash to allow retrieval through a client-side AJAX request from a user’s browser. Output fields are identical to those listed for the Recent Changes API.
https://www.supersaas.com/api/agenda/<schedule_id>.jsonxml?user=<user_id>&api_key=<admin_api_key>&from=<last_retrieval>
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 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). |
user | Either 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_key | The 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 | An MD5 hash containing the account name, API key and username. Ignored if you send the account API Key via api_key . |
slot | When 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, 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:
https://www.supersaas.com/api/agenda.jsonxml?user=<user_id>&api_key=<admin_api_key>&account=<account_name>&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
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).
https://www.supersaas.com/api/free/<schedule_id>.jsonxml?from=<from_time>&api_key=your_api_key
Parameter | Value |
---|---|
schedule_id | The ID 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 |
from | Only return free spaces that occur after this time. Should be in the format YYYY-MM-DD HH:MM:SS in local time. |
api_key | The 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 include full slots that no longer have availability. (capacity schedule only) |
maxresults | (Optional) Limit the number of returned results. Default is 10 . |
If you call this endpoint repeatedly, we recommend including an If-Modified-Since
header.
This will allow the server to quickly respond with 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 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": "2025-01-18T13:00:00", "finish": "2025-01-18T15:00:00", ... }, { "start": "2025-01-18T15:00:00", "finish": "2025-01-18T18:00:00", ... } ] }
<slots> <slot start="2025-01-18 13:00:00" finish="2025-01-18 15:00:00"> ... </slot> <slot start="2025-01-18 15:00:00" finish="2025-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 schedules, this will always be 1 . Will be 0 for slots marked as having no capacity limit. |
All times are returned in the time zone for the account, and in the format YYYY-MM-DD HH:MM:SS
, so irrespective of the time 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 creating appointments in a service-type schedule and while you can create appointments inside slots in a capacity-type 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.
POST /api/bookings.json
<?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 message.
The fields that you can supply are determined on the Configure > Process tab. The settings there also determine which values are optional and which are required. 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 number at the end of the URL in your browser’s address bar |
api_key , checksum | (Optional) See the authentication page, 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. Pass either the resource ID or the resource name |
booking[full_name, | If any of these attributes are present they are stored unchanged as UTF-8 encoded strings |
booking[country] | (Optional) If present it should be a two character ISO 3166-1 country code, if not present the account country is assumed |
booking[email] | The email address of the user. Ignored if you use the email address as login name. |
booking[field_1,field_2, | 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. |
booking[form_id] | (Optional) If a form with this ID exists in your account it will be connected to this booking. |
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:
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 more easily be created by sending a JSON encoded body in the request. The example below has the authentication and schedule ID in the URL, and the appointment information in the JSON body.
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" }
Illustrative Usage: Capacity Schedule
To create an appointment in the capacity schedule with ID <schedule_id>
, you would send the following HTTP POST request:
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
Or with a JSON encoded body in the request:
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", ... }
If a booking contains a custom form then adding form=true
will add the attached form to the output. The format is identical to that produced by the Form API.
When reading data, the retrieved document will contain the following fields in addition to the ones listed above:
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 PERSON 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 |
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=2025-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.
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.
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.
_method=DELETE
instead.