FormAssembly.com is a web-based form management solution that allows anyone to easily create online forms and collect data. FormAssembly is available in different flavors, cloud-hosted (SaaS) or on-premises, and all editions provide a secure REST API for interacting with user accounts and exporting data.
Before you can start building an application using the FormAssembly API, check out the FormAssembly Developer Hub for information on how to register, obtain a CLIENT_ID, and get access to a sandbox.
The endpoint, in API parlance, is the destination URL for your API requests. The endpoint will vary depending on the FormAssembly edition you're interacting with.
Edition | Endpoint | Note |
---|---|---|
FormAssembly Developer Sandbox | https://developer.formassembly.com/api_v1/ | For development and testing only |
FormAssembly.com | https://app.formassembly.com/api_v1/ | |
FormAssembly Enterprise Cloud | https://instance_name.tfaforms.net/api_v1/ | Adjust instance_name as needed |
FormAssembly Enterprise On-Site | https://your_server/path/to/formassembly/api_v1/ | Adjust your_server and path as needed |
From this point on, we'll use the FormAssembly.com endpoint. Just remember to adjust the URIs to match your own FormAssembly edition.
Before you can interact with the API, you must obtain a CLIENT_ID
and a CLIENT_SECRET
code. This is done by completing the registration process on the particular instance you are targeting. For the Developer Sandbox and FormAssembly.com, you must register through the FormAssembly Developer Hub. For Enterprise instances, the FormAssembly administrator can register your app.
Authorization is the mechanism that lets FormAssembly users decide which applications can access their account through the API. Authorizations are handled using the OAuth2 protocol.
If you're not familiar with OAuth2 interactions, it can be helpful to look at the documentation of other APIs, such as this one for the Google API, explaining how OAuth2 works in detail.
The key point of OAuth2 is that it allows a user of FormAssembly (let's call them Adam), to authorize a client (you) to take actions in FormAssembly as if you were Adam. For example, you could write an application, which when authorized by Adam, could download and display a list of all of Adam's forms along with associated metrics, e.g., number of responses, dropout rates, etc. This data could then be used by you to generate custom reports for Adam.
To request a user's authorization, your application must follow these steps.
CLIENT_ID
: The unique client ID generated by FormAssembly for your client application (see Registration above).RETURN_URL
: The URL that your user will be returned to when they complete the authorization step on FormAssembly. This value must be URL-encoded.
FormAssembly will append the code query string parameter to your RETURN_URL when returning the user to the URL. For instance, redirect_uri=https%3A%2F%2Fwww.yourapp.com
(note that the value is URL-encoded) will result in the user being taken to https://www.yourapp.com?code=XXXXXXXXXX
after authorizing FormAssembly.
Retrieve the code from the query string. You will need it to obtain the access token.
Execute a HTTP request from your server (do not direct the user) to request an access token.
- URL: https://app.formassembly.com/oauth/access_token
- HTTP Method: POST
- Post Data:
Parameter Name | Value | Comment |
---|---|---|
grant_type | authorization_code | Use this value as-is |
type | web_server | Use this value as-is |
client_id | CLIENT_ID | Use your unique client application ID issued by FormAssembly |
client_secret | CLIENT_SECRET | Use your unique client application secret issued by FormAssembly |
redirect_uri | RETURN_URL | The same RETURN_URL used in Step 1 |
code | CODE | The code parameter you obtained in Step 2 |
The response to this request will be a JSON array, like so:
{ "access_token":"XXXXXXXXXXXXXX",
"expires_in":XXXXX,
"scope":XXXX,
"refresh_token":"XXXXXXXXXXXX" }
Store the access_token
value. You'll need it for every API request on the user account. Since the access token is valid for only one user account, you will typically obtain multiple access_token from multiple users, and you must store and manage those tokens accordingly.
A HTTP GET request to:
https://app.formassembly.com/api_v1/forms/index.json?access_token=ACCESS_TOKEN
The URL is composed of the following parts:
https://app.formassembly.com/
: The FormAssembly instance.api_v1
: The API version in use. As changes are made to the API, new versions can be released (e.g., under api_v2, api_v3, etc.).forms/index
: The requested data (see API Reference below).json
: The requested format for the response.ACCESS_TOKEN
: The token received in Step 3 of the authorization process.
The response from the request above will result in a JSON-formatted list of the forms in the user's account:
{"Forms":[{
"Form":{
"id":"XXXX", "version_id":"XXXX", "name":"XXXXXXXX",
"category":"XXXX", "subcategory":"XXXX", "is_template":"XXXX",
"display_status":"XXXX", "moderation_status":"XXXX", "expired":"XXXX",
"use_ssl":"XXXX", "user_id":"XXXX",
"created":"XXXXXXXX", "modified":"XXXXXXXX",
"Aggregate_metadata":{
"id":"XXXX", "response_count":"XXXX", "submitted_count":"XXXX",
"saved_count":"XXXX", "unread_count":"XXXX", "dropout_rate":"XXXX",
"average_completion_time":"XXXX", "is_uptodate":"XXXX"
}}
}]}
For an explanation of each field, please see Object Reference.
Several output formats are accepted. See Formats for more details.
FormAssembly supports returning data in two main formats:
- json: A lightweight data exchange format supported by newer languages. Directly parsable by JavaScript.
- xml: An industry standard data exchange format, parsable by almost all languages.
Some endpoints support additional formats, including:
- plist: Used to provide Apple consumable data for Objective-C applications.
- csv: Used as a standard record data exchange format.
- [zip](http://en.wikipedia.org/wiki/ZIP_(file_format\)): A binary data container format.
- https://app.formassembly.com/admin/api_v1/forms/index.json
- https://app.formassembly.com/admin/api_v1/forms/index.xml
Returns a list of all forms in the FormAssembly instance. Only accessible if using FormAssembly Enterprise and an access token from an admin-level user.
- https://app.formassembly.com/api_v1/forms/index.json
- https://app.formassembly.com/api_v1/forms/index.xml
Returns a list of the forms in the user's account, along with associated metadata.
- https://app.formassembly.com/admin/api_v1/forms/view/#FORMID#.json
- https://app.formassembly.com/admin/api_v1/forms/view/#FORMID#.xml
raw
: Bypass form XML element whitelisting.
Return an encoded copy of the form's definition in XML or JSON. Raw
parameter will cause
the returned output to be exactly the content stored by FormAssembly including obsolete or
internal fields. Generally you should not use the raw
parameter.
- https://app.formassembly.com/admin/api_v1/forms/create.json
- https://app.formassembly.com/admin/api_v1/forms/create.xml
xml_data
: xml data formatted per FormAssembly's schema. See output of api_v1/forms/view.builder_version
: string identifier, e.g. "3.4.2","4.0.0","4.0.1","4.1.0","4.2.0".language
: iso language code, e.g. "en-US","fr","zh-CN"name
: string text of the preferred internal application display name.
Create a new form. Expects the additional parameters listed above to be sent as POST.
- https://app.formassembly.com/admin/api_v1/forms/edit/#FORMID#.json
- https://app.formassembly.com/admin/api_v1/forms/edit/#FORMID#.xml
id
: id for existing form.xml_data
: xml data formatted per FormAssembly's schema. See output of api_v1/forms/view.builder_version
: string identifier, e.g. "3.4.2","4.0.0","4.0.1","4.1.0","4.2.0".language
: iso language code, e.g. "en-US","fr","zh-CN"name
: string text of the preferred internal application display name.
Send update to form code. Expects the additional parameters listed above to be sent as POST.
- https://app.formassembly.com/admin/api_v1/forms/delete/#FORMID#.json
- https://app.formassembly.com/admin/api_v1/forms/delete/#FORMID#.xml
id
: id for existing form.
Delete form. Expects the additional parameters listed above to be sent as POST.
- PHP: https://github.com/veerwest/formassembly-api/blob/master/php/fa_api.php
- Python (command-line): https://github.com/veerwest/formassembly-api/blob/master/python/fa_api.py
- Bash (command-line): https://github.com/veerwest/formassembly-api/blob/master/curl/fa_api.sh
- Salesforce: https://github.com/drewbuschhorn/sfdc-oauth-playground/tree/oauth2_drew
- https://app.formassembly.com/api_v1/responses/export/#FORMID#.csv
- https://app.formassembly.com/api_v1/responses/export/#FORMID#.json
- https://app.formassembly.com/api_v1/responses/export/#FORMID#.xml
- https://app.formassembly.com/api_v1/responses/export/#FORMID#.zip
date_from
: Start date for export range.date_to
: End date for export range.filter
: If set toall
, export will include both completed and incomplete responses.response_ids
: Set of comma-delimited response IDs to retrieve.
- https://app.formassembly.com/api_v1/responses/export/1.csv?date_form=01/01/2012&date_to=01/01/2013&filter=all
- would retrieve all responses (including incompletes) created between January 1, 2012 and January 1, 2013.
- https://app.formassembly.com/api_v1/responses/export/1.xml?response_ids=10,11,12
- would retrieve only responses with IDs: 10, 11, 12.
- https://app.formassembly.com/api_v1/connectors/index/#FORMID#.json
- https://app.formassembly.com/api_v1/connectors/index/#FORMID#.xml
Returns a list of the connectors associated with form #FORMID#.
- https://app.formassembly.com/admin/api_v1/connectors/view/#CONNECTORID#.json
- https://app.formassembly.com/admin/api_v1/connectors/view/#CONNECTORID#.xml
Return an encoded copy of the connectors's definition in XML or JSON. #CONNECTORID# can be retrieved from the api_v1/connectors/index/#FORMID# call.
- https://app.formassembly.com/admin/api_v1/connectors/create/#FORMID#/#CONNECTORNAME#.json
- https://app.formassembly.com/admin/api_v1/connectors/create/#FORMID#/#CONNECTORNAME#.xml
event
: string, indicating the stage the connector is run: "beforerender" - before form is displayed to user,"before_save" - when form is saved by user, "interactive" - after form is completed, "background" - after user is shown the form's thank-you page.
Create a new connector. Expects the additional parameters listed above to be sent as POST. #CONNECTORID# can be retrieved from the api_v1/connectors/index/#FORMID# call.
- https://app.formassembly.com/admin/api_v1/connectors/edit/#CONNECTORID#.json
- https://app.formassembly.com/admin/api_v1/connectors/edit/#CONNECTORID#.xml
mapping
: data to set as connector mapping.login
: login data for the connector service.password
: password data for the connector service.
Send update to connector code. Expects the additional parameters listed above to be sent as POST.
- https://app.formassembly.com/admin/api_v1/connectors/delete/#CONNECTORID#.json
- https://app.formassembly.com/admin/api_v1/connectors/delete/#CONNECTORID#.xml
Delete connector.
Returns a list of the themes associated user account.
Return the theme's definition in raw CSS. #THEMEID# can be retrieved from the api_v1/themes/index/#FORMID# call. Note this data may contain links to local urls that will not match a new environment.
name
: string, indicating name of themecss_data
: string, CSS payload for the theme
Create a new theme. Expects the additional parameters listed above to be sent as POST.
id
: int, id of theme to be edited.name
: string, indicating name of themecss_data
: string, CSS payload for the theme
Send update to theme code. Expects the additional parameters listed above to be sent as POST.
Delete the theme.
Returns a list of the form elements available to the user.
Return an XML copy of the element's definition in raw CSS. #ELEMENTID# can be retrieved from the api_v1/form_elements/index.xml call. Note this data may contain links to local urls that will not match a new environment.
xml_data
: string, XML payload for FormAssembly FormBuildername
: string, name for elementcomments
: string, TBDcategory
: string, system level category, (leave blank by default)subcategory
: string, user defined categorybatch
: int, TBD - leave blank
Create a new form element. Expects the additional parameters listed above to be sent as POST.
id
: int, id of element to be edited.xml_data
: string, XML payload for FormAssembly FormBuildername
: string, name for elementcomments
: string, TBDcategory
: string, system level category, (leave blank by default)subcategory
: string, user defined categorybatch
: int, TBD - leave blank
Send update to element code. Expects the additional parameters listed above to be sent as POST.
Delete the element.
Trigger a reset of the aggregate data counters (unread, read, saved, etc.) that may be out of sync after import runs.
Object | Description | Example |
---|---|---|
"id":"XXXX" | Unique integer value identifying the form within the FormAssembly instance. Every form has a single unique ID in the form of an integer. Can be used to construct a valid form URL, e.g., http://app.formassembly.com/forms/view/XXXX | 1 |
"version_id":"XXXX" | Unique integer ID identifying the current version (revision) of the form. | 1 |
"name":"XXXXXXXX" | HTML-encoded string representing the form's name as displayed in the user's FormAssembly form index list. Not to be confused with the Form Title, found in the form's XML definition. | "Mine & Yours Form" |
"category":"XXXX", | String representing one of the system-wide default form organizational categories. Can be an empty string for uncategorized forms. | "Contact Forms" |
"subcategory":"XXXX", | String representing one of the user-created organizational categories. Can be an empty string for uncategorized forms. | "IBM Contact Forms" |
"is_template":"XXXX", | Integer specifying whether or not the form is shared as a template publicly. Contact Support for more details. Values 0 : Not a template>1 : Is a template |
0 |
"display_status":"XXXX", | Integer specifying whether or not the form is active or archived. Values 0 : Archived2 : Active |
2 |
"moderation_status":"XXXX", | Integer specifying whether or not the form is moderated (under review for suspicious content). Values 0 : Not checked2 : Reviewed and approved3 : Reviewed and denied |
0 |
"use_ssl":"XXXX", | Integer representing if the form must be displayed over HTTPS. If true, form URL must contain https:// . |
|
"created":"XXXXXXXX" | String timestamp representing the date the form was created. | "created":"1983-01-01 23:59:59" |
"modified":"XXXXXXXX" | String timestamp representing the last time the form or any of its settings were modified. | "modified":"2012-06-17 17:50:12" |
"expired":"XXXX" | String timestamp representing the date the form was marked for deletion, if any. | "expired":null |
If you are developing for an existing Enterprise instance, you will need to self-register your app by following the instructions below.