Documentation
Print page

Form API

SuperSaaS offers a way to capture additional information from the user using custom forms. Custom forms can be attached to users or appointment, or they can be standalone. The API accepts data as URL-encoded parameters or as a JSON-encoded body and responds with a JSON document.

API Authentication

The API 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.

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 and SuperSaaS, 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")

Usage

There are two ways to use this API. The first way is to retrieve all forms, optionally from a certain date. To do this you 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 way to use this API is to retrieve only one specific form. This can be done with 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 was 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,
    ...
  }
]

And you get 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 are in the JSON file. Not all fields are present if you retrieve multiple forms.

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.