The FormSmarts API & Webhook Client

The FormSmarts API client allows you to quickly automate online form workflows with a simple and intuitive Python interface.

The FormSmarts API & Webhook Client

The FormSmarts API client allows you to automate form workflows with simple Python programs:

• Take action immediately when a form is submitted with a webhook. You could for example use a webhook to add the information submitted to your CRM or integrate the data to a Microsoft Word document and send it to a staff for review.
• Create automations to search form entries (by date, email address or phone number) and add notes and tags or edit form entries with the FormSmarts API.

The API & Webhook Client is a fully supported part of FormSmarts. If Python is not your things, feel free to reach out to FormSmarts Support, so we help you set it up automations.

Here is a short code example that:

1. Sends a copy of the form entry to a member of staff if the person checked a box asking to be contacted
2. Adds the person's email to a mailing list if they agree to subscribe

from formsmarts_api import APIAuthenticator, FormEntry
auth = APIAuthenticator('my_acc_id', 'my_api_key')
entries = FormEntry.search_by_dates(auth, form_id='lqh', start_date='2025-05-05')
for e in entries:
    if e.fields_by_name('Contact me to discuss my needs')[0].value:
        e.add_tag('review')
        e.share('manager@example.com')
    if e.fields_by_name('Subscribe to the monthly newsletter')[0].value:
        mailing_list.add(e.fields_by_type('email')[0].value)

API Client for Python

The FormSmarts Webhook & API Client for Python allows FormSmarts members to search, access and edit form submissions and any attachments (uploaded files). It supports the following functions:

API

• API authentication
• Search form submissions FormEntry.search()
• Retrieve form responses submitted between two dates FormEntry.search_by_dates()
• Get an individual form submission FormEntry.fetch()
• Share a form submission FormEntry.share()
• Download an individual form submission as a PDF FormEntry.download_pdf()
• Download a form attachment Upload.download()
• Submit a form FormEntry.submit()
• Upload a form attachment Upload.upload()
• Replace a form attachment Upload.replace()
• Amend a form submission Field.value = 'new value'
• List tags and system tags FormEntry.tags(), FormEntry.system_tags()
• Get the Reference Number of a form entry FormEntry.reference_number
• Find the date & time a form was submitted FormEntry.date_submitted
• Get the ID of the form FormEntry.form_id
• Get the name of form FormEntry.form_name
• Access the submission context of a form entry FormEntry.context
• Get details of the payment associated with of a form entry FormEntry.payment
• Add a tag to form response FormEntry.add_tag()
• Iterate over input fields FormEntry.fields
• Retrieve input fields by type FormEntry.fields_by_type['email']
• Lookup input fields by name FormEntry.fields_by_name['Address']
• Access input fields by Field ID FormEntry.field_by_id[12345]
• Get the value of an input field Field.value
• Get the name of a field Field.name
• Get the datatype of a field Field.type
• Get the ID of a field Field.id

Webhook

• Authenticate a webhook request WebhookAuthenticator.verify_request()
• Create a FormEntry object from a webhook callback FormEntry.create()
• Access all properties of the form entry with the FormEntry object (same as the API)
• Get the amount due associated with the form entry WebhookEntry.amount_due

API Client for Node.JS

We maintain a basic Node.js client that currently only covers API and webhook authentication.

Getting Started

Installation

The client is available as a Python package. Download it and place it with your Python code.

# Import the Python package
import formsmarts_api 

Authentication

The client uses JWT tokens for request authentication, which are generated using your Account ID and API Key.

1. Obtain Credentials: Your Account ID and secret API Key can be found in the FormSmarts Account settings (Account Overview and Security Settings sections).
2. Initialize Authenticator: You must first create an instance of the APIAuthenticator class using your credentials.

Example Authentication Setup:

from formsmarts_api import APIAuthenticator

# It is recommended to load credentials from a secure configuration file or environment variables
FORMSMARTS_ACCOUNT_ID = 'FSA-999999'
FORMSMARTS_API_KEY = 'TqE35BBzxfmxC74YQ4jQCPFx1oKvFhECOfWrbTh8fVMG6viZWiTfvh4dOZSSK71v'

auth = APIAuthenticator(FORMSMARTS_ACCOUNT_ID, FORMSMARTS_API_KEY)

API Reference

The primary class for interacting with form submissions is FormEntry. The Upload class handles file attachments.

FormEntry Class

This class represents a single form submission and provides methods for searching, retrieval, submission, and manipulation of form data.

Upload Class (File Attachments)

Use the Upload class to handle files. For form submissions with attachments, you must first upload the file and then submit the returned Upload ID in the form's fields dictionary.

Form Submission Example (with Upload)

This example demonstrates how to upload a file and then submit a form containing an upload field.

import config
import os.path
from formsmarts_api import APIAuthenticator, APIEntry, Upload, APIRequestError

# Setup Authentication and Form IDs
FORM_ID = 'lqh'
UPLOAD_FIELD_ID = 122621 # ID of the file upload field on your form
auth = APIAuthenticator(config.FORMSMARTS_ACCOUNT_ID, config.FORMSMARTS_API_KEY)
fields = {
    122619: 'Jane Doe',
    122620: 'blackhole@formsmarts.net',
    UPLOAD_FIELD_ID: '', # Placeholder for the Upload ID
    123744: "Hello,\nThanks for playing.",
}

def submit_with_upload(path, filename):

    # --- STEP 1: Upload the file ---
    print(f"Uploading {filename}...")
    file = open(os.path.join(path, filename), 'rb')

    try:
        upload_id = Upload.upload(
            auth,
            form_id=FORM_ID,
            field_id=UPLOAD_FIELD_ID,
            io_stream=file,
            filename=filename,
            content_type='image/png' # Set the correct content type
        )
        print(f'Picture uploaded successfully as Upload ID: {upload_id}')

        # Set the upload field value to the returned Upload ID
        fields[UPLOAD_FIELD_ID] = upload_id

        # --- STEP 2: Submit the form ---
        ref_num = APIEntry.submit(auth, FORM_ID, fields)
        print(f'Form submitted successfully. Reference Number: {ref_num}')

    except APIRequestError as err:
        print(f"An API error occurred: {err}")
    finally:
        file.close()

# Example usage (assuming 'test-image.png' is in '/tmp')
# submit_with_upload('/tmp', 'test-image.png')

Webhook Reference

The client includes functionality to authenticate and process incoming webhook requests from FormSmarts.

WebhookAuthenticator Class

The client uses JWT tokens to authenticate webhook callbacks and verify that the requests were indeed submitted by FormSmarts. The tokens are generated using your Webhook Key.

1. Obtain Credentials: You can find your secret Webhook Key in the Security Settings section of your FormSmarts Account.
2. Initialize Authenticator: You must first create an instance of the WebhookAuthenticator class using your credentials.

Example Authentication Setup:

from formsmarts_api import WebhookAuthenticator

# It is recommended to load credentials from a secure configuration file or environment variables
FORMSMARTS_API_KEY = 'TqE35BBzxfmxC74YQ4jQCPFx1oKvFhECOfWrbTh8fVMG6viZWiTfvh4dOZSSK71v'
auth = formsmarts_api.WebhookAuthenticator(config.FORMSMARTS_WEBHOOK_KEY)

FormEntry

The FormEntry class can be instantiated directly from a webhook callback payload.

Method	Description	Parameters	Returns
FormEntry.create()	Creates a FormEntry object using the authenticated webhook callback data, allowing you to access submission data with the same properties as the API.	webhook_payload (JSON/Dictionary body of the webhook request)	FormEntry object

Webhook Example

The code below shows how to write a simple webhook callback in Python with the FormSmarts API & Webhook Client.

Note how we:

1. Verify that the callback was submitted by FormSmarts from the signature in the request headers with WebhookAuthenticator.verify_request()
2. Create a FormEntry object from the body of the request with FormEntry.create()
3. Get the picture upload field with self._entry.fields_by_type('upload')[0]
4. Download the picture and save it to a file with pic.download()

import formsmarts_api
import json
import config

logger = logging.getLogger()

class WebhookExample:

    def __init__(self, event):
        self._event = event
        self._api_auth = formsmarts_api.APIAuthenticator(
            config.FORMSMARTS_ACCOUNT_ID, config.FORMSMARTS_API_KEY
        )
        self._wh_auth = formsmarts_api.WebhookAuthenticator(config.FORMSMARTS_WEBHOOK_KEY)
        self._entry = None

    def process_entry(self):
        try:
            # Verify request is from FormSmarts
            if self._wh_auth.verify_request(self._event['headers']['authorization']):
                # Create a FormEntry object from the webhook message
                self._entry = formsmarts_api.FormEntry.create(
                    json.loads(self._event['body']),
                    api_authenticator=self._api_auth
                )
                self.save_picture()
            except formsmarts_api.APIRequestError as err:
                logger.warning(err)

    def save_picture(self):
        # Lookup up the first upload field and download a copy of the picture
        pic = self._entry.fields_by_type('upload')[0]
        pic.download(open(
            f'/Downloads/{self._entry.reference_number}-{pic.filename}', 'wb'
            ))

def lambda_handler(event, context):
    WebhookExample(event).process_entry()

Webhook Use Cases & Examples

Frequent uses of webhooks include:

• Sending notifications by SMS, to Microsoft Teams or Slack based on preset conditions
• Generating Word or PDF documents
• Saving the information submitted to a local database
• Subscribing/unsubscribing an email address from a mailing list

Automation API Webhook Python Node.JS