Developer documentation
Back to index

Form API

If you are using a stand-alone custom form to capture additional information from the customer, you can use the form API to retrieve this data. Custom forms can also be added as part of the registration process or attached to each booking. In these cases, it may be easiest to use the user database API or appointment database API instead.

API Authentication

The API supports 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. Avoid including the account password in a call when accessing the API from a client browser as it would reveal your password to anyone looking at the HTML source.

For additional security you can authenticate with an MD5 hash instead of a password. The hash is calculated from a concatenated string that includes your account name and account password. Since it includes the account password, which is only known to you, it cannot be calculated by anyone else. Most languages provide an easy way to calculate an MD5 hash, for example:

PHP: $checksum = md5("Your_account_nameYour_account_password")
Ruby: checksum = Digest::MD5.hexdigest("Your_account_nameYour_account_password")

Using the form API

There are two ways to use this API. The first is to retrieve a subset of user-completed forms related to a specific template. You can also specify a date which will only retrieve forms created after this date. To do this, select the relevant form in the “Try it out” box on the left (the form name/s will only be visible when logged in to your account). Then you can send a GET request with the following URL:

Try it out
No forms found,
showing placeholder data
https://www.supersaas.com/api/forms?form_id=<form_id>&account=&password=<password>

The second option is to retrieve a single form. In this case you’ll need the form ID (obtained using a webhook or through downloading a schedule’s bookings with the form attached). Once you have the form ID you can paste it in place of “id” in this URL:

https://www.supersaas.com/api/forms?id=<id>&account=&password=<password>
This tutorial can display code snippets relevant to your account if you log in.

The table below describes some of the possible input values that can be used as URL parameters in this API:

Input Values
ParameterValue
form_idThe ID of the form definition you want to retrieve. You can obtain this number by looking at the Configure Overview page of the form. It is the number at the end of the URL in your browser’s address bar
idThe ID of the form you want to retrieve. You can find this number on the Supervise screen of the form
from(Optional) The time in the format YYYY-MM-DD HH:MM:SS in UTC to show forms updated after that time
passwordThe administrator password for the account to which the form belongs. You can also omit this field and use HTTP Basic Authentication or an MD5 hash instead.

If the request is successful then you can expect the following result in JSON when you retrieve multiple forms:

[
  {
    "id": 12345,
    "reservation_process_id": 67890,
    "content": {
      "1": "field 1",
      "2": "field 2"
    },
    "created_on": "2017-03-15T00:00:00Z",
    "updated_on": "2017-03-15T00:00:00Z",
    "user_id": 0
  },
  {
    "id": 23456,
    ...
  }
]

You’ll see the following JSON when you retrieve a single form:

{
  "id": 12345,
  "reservation_process_id": 67890,
  "content": {
    "1": "field 1",
    "2": "field 2"
  },
  "created_on": "2017-03-15T00:00:00Z",
  "updated_on": "2017-03-15T00:00:00Z",
  "super_form_id": 34567,
  "deleted": false,
  "user_id": 0
}

The table below describes the meaning of the fields that can be found in the JSON file.

Output Values
ParameterValue
idThe ID of the form.
reservation_process_idThe ID of the reservation process to which this form belongs. This is zero if the form belongs to a user and it has a null value if the form is a stand-alone form.
contentThis object contains the form’s content and which fields the user has completed.
created_onThe time in UTC when the form was created.
updated_onThe time in UTC when the form was last updated.
super_form_idThe ID of the form definition this form belongs to (only when retrieving a single form).
deletedShows whether or not the form has been deleted (only when retrieving a single form).
user_idThe ID of the user who created the form. Is null when no user was logged in and zero when it was created by the admin.