API – Formsite Support

Introduction

The Formsite API allows external applications to programmatically retrieve your form results. The API is based on a REST model with JSON output.

API access requires a Professional level Formsite account.

The API Page

The basic information you'll need to create API requests can be found on your form's "Settings -> Integrations -> Formsite API" page, including:

Your account's access token.
Your form's API base URL.
IDs for referencing form items, form meta information, Results Views, etc.

Your Access Token

Your access token is like your API password and must be included in every API request. It gives access to all your forms and results so, as with any password, keep it safe and only share it with those you trust with your data.

Include your access token by using the HTTP Authorization header:

Authorization: bearer your_token_value

Rate Limits

Your account is limited to 50 API calls per minute and 10,000 total API calls per day. If you exceed your rate limit, or if the server is too busy to handle your request, it will return an error with a 429 HTTP status code.

If you have a business case with a need for higher limits, please contact support.

API Actions

The base URL for all API actions is:

https://{server}.formsite.com/api/v2/

Set the server prefix to match the server your account is located on. Most action URLs will also need your user directory (user_dir) and form directory (form_dir). These values are the same as used in your form links.

Responses with a 200 HTTP status code indicate success. 4xx and 5xx HTTP status codes indicate errors.

Note: URL parameters must be URL encoded. For example, spaces need to be encoded as %20. Many common programming languages such as Java, JavaScript, and PHP have built-in functions to do this.

Get Forms

Get all forms.

GET https://{server}.formsite.com/api/v2/{user_dir}/forms

parameter	value	default	description
no additional parameters	-	-	-

{
    "forms": [
        {
            "description": "Internal description...",
            "directory": "form123",
            "name": "Customer Survey",
            "publish": {
                "embed_code": "<script>...</script>",
                "link": "https://fs1.formsite.com/example/form123/index.html"
            },
            "state": "open",
            "stats": {
                "filesSize": 0,
                "resultsCount": 100
            }
        }
    ]
}

The "forms" array will contain data for each form:

description: Optional. The form's description, if you've set one on your form's "Settings -> General" page.
directory: The form's URL directory.
name: The form's name.
publish:
- embed_code: The form's share embed code.
- link: The form's share link.
state: The form's open/close state. If the form is open, the value will be "open". If the form is closed, the value will begin with "closed" followed by the reason.
stats:
- filesSize: The total size, in bytes, of any uploaded files the form is storing.
- resultsCount: The number of results the form is storing.

Get Form

Get the specified form.

GET https://{server}.formsite.com/api/v2/{user_dir}/forms/{form_dir}

parameter	value	default	description
no additional parameters	-	-	-

The response will be the same as Get Forms, except the "forms" array will contain only the specified form.

Get Form Items

Get all items for the specified form. Items that don't store results, such as Headings and Images, are not included.

GET https://{server}.formsite.com/api/v2/{user_dir}/forms/{form_dir}/items

parameter	value	default	description
results_labels	Results Labels ID	question labels	Results Labels to apply.

{
    "items": [
        {
            "id": "100",
            "position": 1,
            "label": "What is your name?"
        }
    ]
}

The "items" array will contain data for each item:

id: The item's ID.
position: The item's sequential position the form, starting at position 0.
label: The item's question label.
children: Optional. For item types that are composed of sub-items, such as Matrix and Multi Scale items, a list of item IDs that are sub-items of this item.

Item data can be used to label results data by matching item IDs from this action to item IDs from the Get Form Results action.

Get Form Results

Get all results for the specified form.

GET https://{server}.formsite.com/api/v2/{user_dir}/forms/{form_dir}/results

parameter	value	default	description
limit	number	100	Max number of results to get.
page	number	1	Page number, if results exceed "limit".
after_date	ISO 8601 UTC date or YYYY-MM-DD HH:MM:SS local date	no constraint	Get results after this date.
before_date	ISO 8601 UTC date or YYYY-MM-DD HH:MM:SS local date	no constraint	Get results before this date.
after_id	number	no constraint	Get results after this result ID.
before_id	number	no constraint	Get results before this result ID.
sort_id	meta or item ID	"result_id"	Sort by item with this ID.
sort_direction	"asc" or "desc"	"desc"	Sort direction.
results_view	Results View ID	all data	Results View to apply.
search_equals[x]	string	none	Get results where item with ID x is equal to this value. For multiple choice item types, use the choice's position number.
search_contains[x]	string	none	Get results where item with ID x contains this value. Only works with text item types.
search_begins[x]	string	none	Get results where item with ID x begins with this value. Only works with text item types.
search_ends[x]	string	none	Get results where item with ID x ends with this value. Only works with text item types.
search_method	"and" or "or"	"and"	How to combine multiple search criteria.

{
    "results": [
        {
            "date_finish": "2019-06-01T17:13:50Z",
            "date_start": "2019-06-01T17:13:01Z",
            "date_update": "2019-06-01T17:13:50Z",
            "id": "123000",
            "login_email": "user@example.com",
            "login_username": "user",
            "payment_amount": 123.00,
            "payment_status": "Payment Successful",
            "result_status": "Complete",
            "user_browser": "Firefox",
            "user_ip": "123.123.123",
            "user_device": "Desktop",
            "user_referrer": "http://example.com/page.html",
            "items": [
                {
                    "id": "100",
                    "position": 0,
                    "value": "text answer"
                },
                {
                    "id": "200",
                    "position": 1,
                    "values": [
                        {
                            "other": "other answer",
                            "position": 0,
                            "value": "multiple choice answer"
                        }
                    ]
                }
            ]
        }
    ]
}

The "results" array will contain data for each result:

date_finish: Optional. The date the result was finished, in ISO 8601 UTC format.
date_start: Optional. The date the result was started, in ISO 8601 UTC format.
date_update: The date the result was most recently modified, in ISO 8601 UTC format.
id: The result's unique ID.
login_email: Optional. If the form has Save & Return enabled, the email associated with this result.
login_username: Optional. If the form has Save & Return enabled, the username associated with this result.
payment_amount: Optional. If the form is an order form, the payment amount.
payment_status: Optional. If the form is an order form, the payment status.
user_browser: The user's browser.
user_ip: The user's IP address.
user_device: The user's device ("Desktop", "Tablet", or "Mobile").
user_referrer: The user's referrer URL. The value will be "N/A" if the referrer was not recorded.
items:
- id: The item's ID.
- position: The item's sequential position on the form, starting at position 0.
- value or values: Text item types will use value with a string value. Multiple choice item types will use values with an array of chosen choice values.

A maximum of 100 results will be returned for a single request. You can use the page parameter on subsequent requests to get any remaining results. Pagination information is included in the HTTP headers:

Pagination-Limit: The results per page limit. Set with limit.
Pagination-Page-Current: The page number of the current page of results. Set with page.
Pagination-Page-Last: The page number of the last page of results (the total number of pages).

Item data can be used to label results data by matching item IDs from the Get Form Items action to item IDs from this action.

For best performance, use constraining parameters to request only the results you're interested in. For example, you can use after_id or after_date to get only the results newer than the most recent result you got last time.

You can use the search parameters to find results with specific answers. Text item types can use any of the search parameters, but multiple choice and meta item types can only use the "equals" search parameter. For multiple choice item types, search for the answer choice's position number. For meta item types (result_id, result_status, user_ip, or user_referrer), search for the answer as it appears in the output. You can combine multiple search parameters to make and/or searches, but you can't use the same parameter with the same item multiple times. For more advanced searching, start with a simple search and then filter the data further within your application.

Get Webhooks

Get all webhooks for the specified form.

GET https://{server}.formsite.com/api/v2/{user_dir}/forms/{form_dir}/webhooks

parameter	value	default	description
no additional parameters	-	-	-

{
    "webhooks": [
        {
            "handshake_key": "TEST_KEY",
            "event": "result_completed",
            "url": "https://example.com/hook"
        }
    ]
}

The "webhooks" array will contain data for each webhook:

event: The event the webhook is subscribed to.
handshake key: Optional. The webhook's handshake key.
url: The webhook's post URL.

Create or Update Webhook

Create a new webhook for the specified form. Or, if there's an existing webhook with the specified URL, update it.

POST https://{server}.formsite.com/api/v2/{user_dir}/forms/{form_dir}/webhooks

parameter	value	default	description
event	"result_completed"	none	The event to subscribe to. Currently, the only supported event is "result_completed".
handshake_key	string	none	Optional. Handshake key.
url	URL	none	The URL the webhook will post to.

"webhook": {
    "handshake_key": "TEST_KEY",
    "event": "result_completed",
    "url": "https://example.com/hook"
}

The response will be the same as Get Webhooks, except the "webhook" object will contain only the created/updated webhook.

A webhook will post to its URL each time a form result is completed, using the same data format as Get Results. If you've specified a handshake key, it will be included in the posted object as an extra property named "handshake_key".

Note: If a webhook receives a response with a 410 HTTP status code, it will automatically unsubscribe and delete itself.

Delete Webhook

Delete an existing webhook for the specified form.

DELETE https://{server}.formsite.com/api/v2/{user_dir}/forms/{form_dir}/webhooks

parameter	value	default	description
url	URL	none	Delete the webhook with this post URL.

{ }

The response will be an empty object.

Errors

A 4xx or 5xx HTTP status code indicates an error occurred. When there's an error, the "error" object is returned instead of the action's normal response.

{
    "error": {
        "message": "Invalid access token.",
        "status": 401
    }
}

The "error" object will contain data describing the error:

message: The error message.
status: The HTTP status code, in case you're unable to directly get the HTTP status code.

status code	description
401	Authentication info is missing or invalid.
403	Forbidden.
404	Path or object not found.
422	Invalid parameter.
429	Too many requests or too busy.
5xx	Unexpected internal error.