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.Formstack(api_token: str | None = None)

Instantiate Formstack class.

Parameters:

api_token – API token to access the Formstack API. Not required if the FORMSTACK_API_TOKEN env variable is set.

get_folders() → Table

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

Get all forms on your account.

Parameters:

• 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

Get the details of the specified submission.

Parameters:

id – int ID for the submission to retrieve.

Returns:

Dictionary

Submission data.

get_form_submissions(form_id: int, **query_params) → Table

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

Get all fields for the specified form.

Parameters:

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

Returns:

Table Class

A Table with the fields on the form.