API

Documentation Home

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

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:

codedescription
0Unexpected error, contact support
1Invalid or incomplete API URL
2Invalid URL parameter value
3The system is too busy to process your request
100Invalid API key
101Invalid user
102Invalid form
103Invalid result ID

Copy Form

Copy a form into another account.

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

parametervaluedefaultdescription
fs_destination_accountstringcurrent accountUsername of the account into which to copy the form.
fs_destination_formstringoriginal form nameName 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

parametervaluedefaultdescription
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

parametervaluedefaultdescription
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

parametervaluedefaultdescription
fs_securenonenormal (http) URLsGet 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/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

parametervaluedefaultdescription
fs_limitnumber (less than 100)100Max number of results.
fs_min_dateYYYY-MM-DD[ HH:MM:SS]no constraint
Results submitted on or after this date.
fs_max_dateYYYY-MM-DD[ HH:MM:SS]no constraintResults submitted on or before this date.
fs_min_idresult IDno constraintResults greater or equal to this id.
fs_max_idresult IDno constraintResults less than or equal to this id.
fs_pagenumber1Page number, if results exceed fs_limit.
fs_sortmeta or item IDsort by result id
Sort by this column.
fs_sort_direction"asc" or "desc""desc"Sort in this direction.
fs_search_equals_xstringnoneResults where x is equal to this term.
fs_search_contains_xstringnoneResults where x contains this term.
fs_search_begins_xstringnoneResults where x begins with this term.
fs_search_ends_xstringnoneResults where x ends with this term.
fs_search_empty_xnonenoneResults where x is empty.
fs_search_not_empty_xnonenoneResults where x is not empty.
fs_search_method"and" or "or""and"How to combine multiple search criteria.
fs_viewView IDall data (View 11)View to apply to the results.
fs_include_headingsnoneno headingsInclude column headings with data.
fs_custom_labelsCustom Labels IDnoneApply 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

parametervaluedefaultdescription
fs_min_dateYYYY-MM-DD[ HH:MM:SS]no constraint
Results submitted on or after this date.
fs_max_dateYYYY-MM-DD[ HH:MM:SS]no constraintResults submitted on or before this date.
fs_min_idnumberno constraintResults greater or equal to this id.
fs_max_idnumberno constraintResults 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