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 Pro 1 level or higher Formsite account.
Note: This API replaces the original v1 API, which is now deprecated. The v1 API will be retired at the end of 2021.
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: bearer your_token_value
Your account is limited to 50 API calls per minute and 2,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.
The base URL for all API actions is:
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.
Get All Forms
Get all forms.
|no additional parameters||-||-||-|
"description": "Internal description...",
"name": "Customer Survey",
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.
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.
filesSize: The total size, in bytes, of any uploaded files the form is storing.
resultsCount: The number of results the form is storing.
Get the specified form.
|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.
|results_labels||Results Labels ID||question labels||Results Labels to apply.|
"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 Result action.
Get Form Results
Get all results for the specified form.
|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.|
"payment_status": "Payment Successful",
"value": "text answer"
"other": "other answer",
"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_os: The user's operating system.
user_referrer: The user's referrer URL. The value will be "N/A" if the referrer was not recorded.
id: The item's ID.
position: The item's sequential position on the form, starting at position 0.
values: Text item types will use
valuewith a string value. Multiple choice item types will use
valueswith 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
Pagination-Page-Current: The page number of the current page of results. Set with
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_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 (
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.
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.
"message": "Invalid access token.",
The "error" object will contain data describing the error:
message: The error message.
status: The HTTP status code, in case you are unable to directly get the HTTP status code.
|401||Authentication info is missing or invalid.|
|404||Path or object not found.|
|429||Too many requests or too busy.|
|5xx||Unexpected internal error.|