Formstack

Overview

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

Note

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.

Quick Start

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.

from parsons.formstack import Formstack

# Instantiate the Formstack class using the FORMSTACK_API_TOKEN env variable
fs = Formstack()

# Instantiate the Formstack class using the api token directly
fs = Formstack(api_token="<your api token>")

# Get all of the folders in our account
folders = fs.get_folders()

# Find the ID of the "Data" folder
data_folder_id = None
for folder in folders:
    if folder["name"] == "Data":
        data_folder_id = folder["id"]
        break

# If we found the "Data" folder, get all of the forms in it
if data_folder_id is not None:
    forms = fs.get_forms(folder_id=data_folder_id)

    print(forms)

API

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

Instantiate Formstack class.

Args:

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

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

Get all forms on your account.

Args:

form_name: string, optional: Search by form name.
folder_id: int, optional: Return forms in the specified folder.

Returns:

Table Class: A table with the forms data.

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

Get the details of the specified submission.

Args:

id: int: ID for the submission to retrieve.

Returns:

Dictionary: Submission data.

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.

Args:

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

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

Get all fields for the specified form.

Args:

form_id: int: The form ID for the form of the submissions.

Returns:

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