Formstack¶

Overview¶

Formstack is a service that provides an advanced online form builder. This connector allows you to load data from the Formstack API.

Authentication

Formstack uses OAuth2 user access tokens to handle authentication. “Access tokens are tied to a Formstack user and follow Formstack (in-app) user permissions.” You can acquire an OAuth2 token in the Formstack API overview.

You can pass the token to the Formstack object as the api_token keyword argument, or you can set the environment variable FORMSTACK_API_TOKEN.

Quickstart¶

To instantiate the Formstack class, you can either store your access token in the FORMSTACK_API_TOKEN environment variable or pass it in as an argument.

Instantiate the Formstack class using the FORMSTACK_API_TOKEN environment variable¶

from parsons.formstack import Formstack
fs = Formstack()

Instantiate the Formstack class using the api token directly¶

from parsons.formstack import Formstack
fs = Formstack(api_token="<your api token>")

Find the ID of folder “Data” and get all the forms in it¶

folders = fs.get_folders()
data_folder_id = None
for folder in folders:
   if folder["name"] == "Data":
      data_folder_id = folder["id"]
      break

if data_folder_id is not None:
   forms = fs.get_forms(folder_id=data_folder_id)
   print(forms)

API¶

class parsons.formstack.formstack.Formstack(api_token: str | None = None)[source]¶

Instantiate Formstack class.

Parameters:: api_token (str | None) – API token to access the Formstack API. Not required if the FORMSTACK_API_TOKEN env variable is set.

get_folders() → Table[source]¶

Get all folders on your account and their subfolders.

Returns:

Table Class: A Table with the folders data.

Return type:

Table

get_forms(form_name: str | None = None, folder_id: int | None = None) → Table[source]¶

Get all forms on your account.

Parameters:

form_name (str | None) – string, optional Search by form name.
folder_id (int | None) – int, optional Return forms in the specified folder.

Returns:

Table Class: A table with the forms data.

Return type:

Table

get_submission(id: int) → dict[source]¶

Get the details of the specified submission.

Parameters:

id (int) – int ID for the submission to retrieve.

Returns:

Dictionary: Submission data.

Return type:

dict

get_form_submissions(form_id: int, **query_params) → Table[source]¶

Get all submissions for the specified form.

Note this only returns the meta-data about the submissions, not the answer data, by default. To get the responses pass data=True as a query param.

For more useful options, such as how to filter the responses by date, check the Formstack documentation.

Parameters:

form_id (int) – int The form ID for the form of the submissions.
query_params – kwargs Query arguments to pass to the form/submissions endpoint.

Returns:

Table Class: A Table with the submission data for the form.

Return type:

Table

get_form_fields(form_id: int) → Table[source]¶

Get all fields for the specified form.

Parameters:

form_id (int) – int The form ID for the form of the submissions.

Returns:

Table Class: A Table with the fields on the form.

Return type:

Table