Online Form Builder - API Documentation

API

Introduction

We have 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 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 API is fully functional and no longer in beta status. We are always looking to add new features based on user feedback. 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->Third Party->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->Third Party->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 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_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

Copy Form

Copy a form into another account.

POST https://fsX.formsite.com/api/users/yourAccount/forms/yourForm/copy

parameter	value	default	description
fs_destination_account	string	current account	Username of the account into which to copy the form.
fs_destination_form	string	original form name	Name of the new form.

POST https://www.formsite.com/api/users/demo/forms/BrandAwareness/copy?fs_api_key=demo_key&fs_destination_account=demo&fs_destination_form=Copied+Form

<fs_response status="success">
  <form id="0">
    <name>Copied Form</name>
    <description>Determine how familiar people are with your brand or organization.</description>
    <directory>form01234567</directory>
  </form>
</fs_response>

Information for the new 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 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	-	-	-

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

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

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

<fs_response status="success">
  <status>
    <state>open</state>
    <last_modified>2009-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 Publish

Get publishing URLs and embed code for a form in your account.

GET https://fsX.formsite.com/api/users/yourAccount/forms/yourForm/publish

parameter	value	default	description
fs_secure	none	normal (http) URLs	Get secure (https) URLs.

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

<fs_response status="success">
  <publish>
    <url type="normal">
      http://www.formsite.com/demo/BrandAwareness/index.html
    </url>
    <url type="printer">
      http://www.formsite.com/app/FormSite?EParam=mfELfeHTmyft7IotM1x2Durmxl...
    </url>
    ...
  </publish>
</fs_response>

The URL for each publish link will be contained in a "url" tag. The HTML for each embed code will be contained in a "code" tag.

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.
fs_custom_labels	Custom Labels ID	none	Apply custom labels to results.

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_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 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_response status="success">
<count>5</count>
</fs_response>

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

Additional Information

Planned near-future API transactions:

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

Documentation Home

API