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.

The API page

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

  • Your account's 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 your form's "Form Settings->Integrations->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:

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 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
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://fsX.formsite.com/api/users/yourAccount/forms?fs_api_key=YOURKEY

<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://fsX.formsite.com/api/users/yourAccount/forms/BrandAwareness/status?fs_api_key=YOURKEY

<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 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
no additional parameters - - -
GET https://fsX.formsite.com/api/users/yourAccount/forms/BrandAwareness/publish?fs_api_key=YOURKEY

<fs_response status="success">
  <publish>
    <url type="normal">
      https://www.formsite.com/demo/BrandAwareness/index.html
    </url>
    <url type="printer">
      https://www.formsite.com/form_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 Results 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://fsX.formsite.com/api/users/yourAccount/forms/BrandAwareness/results?fs_api_key=YOURKEY

<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://fsX.formsite.com/api/users/yourAccount/forms/BrandAwareness/results/count?fs_api_key=YOURKEY

<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.)
Over 1 Billion forms submitted