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

Authentication

You need to include your API key with each request, as a header or a parameter. Please refer to the Authentication page for details.

Using the form API

There are two ways to use this API. The first is to retrieve a subset of user-completed forms. 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 Form: No forms found,
showing placeholder data

From:

https://www.supersaas.com/api/forms?form_id=<form_id>&account=<account_name>&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=<account_name>&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 the possible input values that can be used as URL parameters in the request:

Input values
Parameter	Value
`form_id`	The 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
`id`	(Optional) The ID of the form you want to retrieve, if you want to retrieve a single form. 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 this time
`limit`	(Optional) Indicate the maximum number of results you want returned, default is 100. For large requests you can make multiple requests and add an `offset` parameter to page through the results
`api_key`	The 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
Parameter	Value
`id`	The ID of the form.
`reservation_process_id`	The 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.
`content`	This object contains the form’s content and which fields the user has completed.
`created_on`	The time in UTC when the form was created.
`updated_on`	The time in UTC when the form was last updated.
`super_form_id`	The ID of the form definition this form belongs to (only when retrieving a single form).
`deleted`	Shows whether the form has been deleted (only when retrieving a single form).
`user_id`	The 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.