The v2 API is modernized to take advantage of new features that have been developed since the v1 API was launched in 2008. Most notably, the v2 API replaces the outdated XML format with JSON.
The v2 API uses an updated access token authentication method. The v1 fs_api_key parameter has been replaced with the v2 Authorization header. Your access token has been initialized to share the same value as your v1 API key, so you can continue to use the same value while you're migrating. We've also added the ability to reset your access token on your form's "Settings -> Integrations -> Formsite API" page. After you're no longer using the v1 API, we recommend you reset your access token to disable your old key and use a new token value going forward. For more information, see the "Your Access Token" section in the API documentation.
The v2 API returns response status info with HTTP status codes to more closely align to REST standards. A 200 status code indicates a success and a 4xx or 5xx status code indicates an error. For more information, see the "Errors" section in the API documentation.
Additionally, the following behavior has changed:
- For a result's
result_statusfield, the values "Confirmed" and "Unconfirmed" have been replaced with "Complete" and "Incomplete". In v1, the values would normally use "Complete" and "Incomplete", but if the form was an order form it would instead use "Confirmed" and "Unconfirmed". Now, all forms will use the same values. - For a result's
date_start,date_finish, anddate_updatefields, the date values are formatted in ISO 8601 format. In v1, the values were formatted in "YYYY-MM-DD HH:MM:SS" format with your account's timezone applied. - For searching, the v1
fs_min_dateandfs_max_dateparameters have been changed to the v2after_dateandbefore_dateparameters. These work basically the same, except they are exclusive (like>and<) rather than inclusive (like>=and<=). - For searching, the v1
fs_min_idandfs_max_idparameters have been changed to the v2after_idandbefore_idparameters. These work basically the same, except they are exclusive (like>and<) rather than inclusive (like>=and<=). - Form status info has been moved from the v1 Get Form Status action to the v2 Get Forms action (to get for all forms) or the Get Form action (to get for a single form).
- Results count info has been moved from the v1 Get Results Count action to the v2 Get Forms action (to get for all forms) or the Get Form action (to get for a single form).
API v1 Reference
Note: Use this information only to maintain existing integrations. Use the v2 API to create new integrations. The v1 API will be retired at the end of 2021.
API v1 URLs
The general format for API requests is:
https://fsX.formsite.com/api/users/yourAccount/forms/yourForm/action?parameters
- METHOD: GET, POST, PUT, or DELETE
- fsX: The server where your account is located (same as in your form URL).
- yourAccount: Your account's URL Extension (same as in your form URL).
- yourForm: Your form's Directory (same as in your form URL).
- action: The API action you are interacting with.
- parameters: Your API key and any additional parameters.
Note: All parameter values 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.
API v1 Responses
The general format for API responses is:
<fs_response status="success">
result
</fs_response>
Error responses will be in the format:
<fs_response status="error">
<error code="code">message</error>
</fs_response>
Error responses will contain one of the following error codes:
| code | description |
|---|---|
| 0 | Unexpected error, contact support |
| 1 | Invalid or incomplete API URL |
| 2 | Invalid URL parameter value |
| 3 | The system is too busy to process your request |
| 100 | Invalid API key |
| 101 | Invalid user |
| 102 | Invalid form |
| 103 | Invalid result ID |
Success responses won't have a number code.
API v1 Actions
Get Forms
Get a list of the forms in your account.
GET https://fsX.formsite.com/api/users/yourAccount/forms
| parameter | value | default | description |
|---|---|---|---|
| no additional parameters | - | - | - |
<fs_response status="success">
<forms>
<form id="0">
<name>Brand Awareness Survey</name>
<description>Determine how familiar people are with your brand or organization.</description>
<directory>BrandAwareness</directory>
</form>
...
</forms>
</fs_response>
Information for each form will be contained in a "form" tag. The value of the "directory" tag can be used in form-specific API URLs (see below).
Get Form Status
Get the status of a form in your account.
GET https://fsX.formsite.com/api/users/yourAccount/forms/yourForm/status
| parameter | value | default | description |
|---|---|---|---|
| no additional parameters | - | - | - |
<fs_response status="success">
<status>
<state>open</state>
<last_modified>2016-07-13 13:54:20</last_modified>
<limit type="items">
<used>16</used>
<total>1000</total>
</limit>
<limit type="results">
<used>5</used>
<total>5000</total>
</limit>
</status>
</fs_response>
Information for each limit will be contained in a "limit" tag. The value of the "state" tag can be used to check if a form is open or closed.
Get Results
Get results for a form in your account.
GET https://fsX.formsite.com/api/users/yourAccount/forms/yourForm/results
| parameter | value | default | description |
|---|---|---|---|
| fs_api_key | string | none | Your account's API key. |
| fs_limit | number | 100 | Max number of results. |
| fs_min_date | YYYY-MM-DD[ HH:MM:SS] | no constraint | Results on or after this date. |
| fs_max_date | YYYY-MM-DD[ HH:MM:SS] | no constraint | Results on or before this date. |
| fs_min_id | result ID | no constraint | Greater or equal to this ID. |
| fs_max_id | result ID | no constraint | Less or equal to this ID. |
| fs_page | number | 1 | Page number, if results exceed fs_limit. |
| fs_sort | meta or item ID | sort by result ID | Sort by this column. |
| fs_sort_direction | "asc" or "desc" | "desc" | Sort in this direction. |
| fs_search_equals_x | string | none | Results where x is equal to this term. |
| fs_search_contains_x | string | none | Results where x contains this term. |
| fs_search_begins_x | string | none | Results where x begins with this term. |
| fs_search_ends_x | string | none | Results where x ends with this term. |
| fs_search_empty_x | none | none | Results where x is empty. |
| fs_search_not_empty_x | none | none | Results where x is not empty. |
| fs_search_method | "and" or "or" | "and" | How to combine multiple search criteria. |
| fs_view | Results View ID | all data | Results View to apply. |
| fs_include_headings | none | no headings | Include column headings with data. |
| fs_custom_labels | Results Labels ID | none | Results Labels to apply. |
A maximum of 100 results will be returned for a single request. You can use the "fs_page" parameter on subsequent requests to get any remaining results. For best performance, use constraining parameters to request only the results you are interested in.
Note: Search parameters are limited to one parameter per search type per item ID (that is, you can't use fs_search_equals_1=X and fs_search_equals_1=Y because it would result in two parameters named fs_search_equals_1).
<fs_response status="success">
<results>
<result id="4145169">
<metas>
<meta id="result_status">Complete</meta>
...
</metas>
<items>
<item id="1" index="1" type="text">
<value>Zenith</value>
</item>
...
</items>
</result>
...
</results>
</fs_response>
Each form result will be contained in a "result" tag. The result's "id" attribute represents the result's reference number. Each individual item's result will be contained in an "item" tag. The item's "id" attribute represents its API id and its "index" attribute represents its sequential position on the form. The value of the item's result will appear in a "value" tag.
Get Results Count
Get a count of the total stored results for a form in your account.
GET https://fsX.formsite.com/api/users/yourAccount/forms/yourForm/results/count
| parameter | value | default | description |
| fs_min_date | YYYY-MM-DD[ HH:MM:SS] | no constraint | Results on or after this date. |
| fs_max_date | YYYY-MM-DD[ HH:MM:SS] | no constraint | Results on or before this date. |
| fs_min_id | number | no constraint | Greater or equal to this ID. |
| fs_max_id | number | no constraint | Less or equal to this ID. |
The count will be contained in a "count" tag.
