Back to index

Form API

Home Developer documentationForm 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.

Authentication

Please refer to the Authentication Page.

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 names will only be visible when logged in to your account). Then you can send a GET request with the following URL:

Try it out
https://www.supersaas.com/api/forms?form_id=<form_id>&account=&api_key=your_api_key

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=&api_key=your_api_key
This tutorial can display code snippets relevant to your account if you log in
This tutorial can display code snippets relevant to your account if you generate an API Key at the bottom of the Account Info page by clicking the Generate button.

The table below describes some 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
api_keyThe administrator API Key for the account to which the form belongs. You can also omit this field and use HTTP Basic Authentication or an MD5 hash instead.
user(Optional) Either the user’s name or ID or foreign key. Limit the output to forms for this user. Use user=0 to get the forms for the administrator

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

The API should return the result in JSON format by default. You can force the result to be returned in XML format by replacing forms in the URLs above with forms.xml. Conversely, you can force the result to be returned in JSON by using forms.json.