Online Form Builder - API Documentation

FormSite API (BETA)

Introduction

FormSite has been developing an extensive API for interacting with forms and results. API access is available to all Professional level accounts. Try our PHP example or Java example to see a working example of the API in action (full source code is included).

The FormSite API is based on a REST model with XML output. JSON and CSV output may be added in the future, based on user demand.

NOTE: The FormSite API will remain in Beta status pending new features and user feedback. During this time, some functionality may change. We encourage you to contact us with any feedback you may have.

The API Page

You can find the API page by using the "Form->API" menu option. The API page contains the basic reference information necessary to create API requests for your form, including:

Your API key
Your form's API URL
IDs for referencing form items, form meta information, and results Views

Your API Key

Your account's API key can be found on the "Form->API" page. This key acts as your API password and must be included in every API request. Just as with any password, keep this key safe and share it only with those you trust with your data.

API URLs

The general format for API requests is:

METHOD https://fsX.formsite.com/api/users/yourAccount/forms/yourForm/transaction?parameters

METHOD: GET, POST, PUT, or DELETE
fsX: The FormSite 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 Form Directory (same as in your form URL)
transaction: The API transaction object you are interacting with
parameters: 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 that can do this.

API Responses

The general format for API responses is:

<fs_result status="success">
result
</fs_result>

Error responses will be in the format:

<fs_result status="error">
<error code="code">message</error>
</fs_result>

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

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_limit	number (less than 100)	100	Max number of results.
fs_min_date	YYYY-MM-DD[ HH:MM:SS]	no constraint	Results submitted on or after this date.
fs_max_date	YYYY-MM-DD[ HH:MM:SS]	no constraint	Results submitted on or before this date.
fs_min_id	result ID	no constraint	Results greater or equal to this id.
fs_max_id	result ID	no constraint	Results less than 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	View ID	all data (View 11)	View to apply to the results.
fs_include_headings	none	no headings	Include column headings with data.

NOTE: 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 (ie you cannot use fs_search_equals_1=X and fs_search_equals_1=Y because it would result in two parameters named fs_search_equals_1).

GET https://www.formsite.com/api/users/demo/forms/BrandAwareness/results?fs_api_key=demo_key

<fs_result 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_result>

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 number of 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 submitted on or after this date.
fs_max_date	YYYY-MM-DD[ HH:MM:SS]	no constraint	Results submitted on or before this date.
fs_min_id	number	no constraint	Results greater or equal to this id.
fs_max_id	number	no constraint	Results less than or equal to this id.

GET https://www.formsite.com/api/users/demo/forms/BrandAwareness/results/count?fs_api_key=demo_key

<fs_result status="success">
<count>5</count>
</fs_result>

The count will be contained in the "count" tag.

Additional Information

Available API transactions:

Get Results
Get Results Count

Planned near-future API transactions:

Modify and Delete Results
Submit New Results
Get Form Stats (number of submissions, remaining storage space, etc.)

Formsite.com