Search API

The Search API allows customers to lookup form submissions by email address, phone number or Reference Number.

The Search API

The Search API¹ returns the same information about form responses as the Search page.

• To look up form responses² associated with an email address or phone number for a specific form, pass its ID in the form_id parameter and submit a GET request
• To search for all form entries² associated with an email address or phone number, submit a GET request without specifying a Form ID
• To retrieve the latest form responses, submit a query with the latest command. Use the form_id parameter to limit results to a specific form.
• Use the tags and system_tags parameters to filter form responses matching specific tags or system tags, or to exclude form responses carrying a tag with the not: prefix. See Filtering by Tags below.

Supported Query Values

The query parameter accepts the following values:

• Email address — returns all submissions containing that email address²
• Phone number — returns all submissions containing that phone number²
• Reference Number — returns the specific form submission identified by that FormSmarts Reference Number
• Stripe Payment ID — returns the submission associated with that Stripe payment (for forms with Stripe payment)
• PayPal Transaction ID — returns the submission associated with that PayPal transaction (for forms with PayPal payment)
• PayPal Subscription ID — returns submissions associated with that PayPal subscription
• PayPal Invoice ID — returns the submission associated with that PayPal invoice ID as shown on PayPal
• latest — returns the most recent form submissions. Use the form_id parameter to limit results to a specific form.

Filtering by Tags

The tags and system_tags parameters take a comma-separated list of tags:

• A plain tag only returns form responses carrying that tag. Several tags are combined with a logical AND: tags=paid,reviewed returns the form responses carrying both the paid and the reviewed tags.
• A tag prefixed with not: excludes the form responses carrying that tag: tags=paid,not:refunded returns the form responses tagged paid that aren't tagged refunded.
• Excluding a tag you also require, e.g. tags=paid,not:paid, is an error and returns an HTTP 400 Bad Request.

The two parameters are independent filters that are combined: tags=reviewed&system_tags=not:api submitted returns the form responses tagged reviewed that were not submitted with the Form Submission API.

API Response

If the request is successful, the API returns an HTTP 200 status and a list of JSON objects with the form submissions matching the email address or phone number specified in the query parameter.

The JSON objects returned currently include:

• The Reference Number of the form response, which you can then use to retrieve the complete form response with the Form Response API.
• The date the form was submitted as an ISO 8601 timestamp

If you search form responses across all your forms (form_id parameter unset), the responses also include:

• The ID of the form
• The name of the form

Draft Form Entries

A search by email address also returns the draft form entries belonging to that address, so you can tell that someone started a form but hasn't submitted it yet. Only the drafts of forms using the Submit for Review workflow are indexed, under the email address of the person the draft belongs to. Drafts have no Reference Number and are returned with a different set of attributes:

• partial_session_id: the first characters of the ID of the draft, enough to identify it without exposing the full session ID
• expires: the date and time the draft expires and is deleted
• status: editable, pending_review or rejected for forms using the Submit for Review workflow
• access_url: a pre-signed URL to open the draft online as a reviewer
• The ID and name of the form, as for submitted entries

Drafts carry no tags, so they aren't returned when the request has a tags or system_tags filter (a not: exclusion doesn't filter them out). They aren't returned by the latest command, by a search by phone number, or by a search by Reference Number or payment ID either. The API Client skips draft entries: check the reference_number attribute if you call the API directly and only want submitted form responses.

Example

This is a sample API response:

[
   {
      "reference_number":"1GZCTWIGK8E5HYPIK0RPMIJT7",
      "date_submitted":"2017-04-29T03:22:21Z",
      "form_id":"1nk5",
      "form_name":"E-Signature Demo"
   },
   {
      "reference_number":"94JSBKMURKW3UTOMVGA0SPWLK",
      "date_submitted":"2017-04-26T11:17:50Z",
      "form_id":"k2a",
      "form_name":"Multimedia Projector Booking Form"
   }
]

If the request fails, the API returns a non-success HTTP status with a JSON object specifying the error.

Authentication

FormSmarts verifies API requests with a JWT token in the Authorization header. You can sign requests with the FormSmarts API Client or a JWT library in your favorite programming language. You'll need to know your FormSmarts Account ID and secret FormSmarts API Key.

You'll find your Account ID in the Account Overview section of your account and your API Key in the Security Settings.

Python Example

The easiest way to use the Search API is with the API & Webhook Client, which provides a Python interface to FormSmarts services. Install it with pip:

pip install formsmarts

The example below searches for all submissions to a specific form matching an email address. Credentials are read from environment variables — never hard-code them in your source.

import os
from formsmarts import APIAuthenticator, FormEntry

auth = APIAuthenticator(os.environ['FS_ACCOUNT_ID'], os.environ['FS_API_KEY'])

for entry in FormEntry.search(auth, form_id='lqh', query='example@example.com'):
    print(entry.reference_number, entry.submitted_at)

Omit form_id to search across all your forms, or pass query='latest' to retrieve the most recent submissions. FormEntry.search() returns a generator that pages through the results transparently and returns complete FormEntry objects, not just the Reference Numbers the API returns.

The example below looks up the latest entries of a form that are tagged paid, but not yet fulfilled, and returns the tags of each entry with the results:

entries = FormEntry.search(
    auth, query='latest', form_id='lqh',
    tags='paid', exclude_tags='fulfilled', return_tags=True
)
for entry in entries:
    print(entry.reference_number, entry.submitted_at, entry.tags)

exclude_tags and exclude_system_tags are how the client sends the not: tag filters described above. return_tags=True returns the tags and system tags with each entry, so reading entry.tags and entry.system_tags doesn't require an extra API request per entry. See the API Client documentation for the full list of options.

If you prefer to call the API directly with an HTTP library or another programming language, here is an equivalent example:

import os
import json
import requests
from formsmarts import APIAuthenticator

FORM_ID = 'lqh'
API_URL = 'https://formsmarts.com/api/v1/entries/search'

auth = APIAuthenticator(os.environ['FS_ACCOUNT_ID'], os.environ['FS_API_KEY'])

resp = requests.get(API_URL, params={'form_id': FORM_ID, 'query': 'example@example.com'},
                    headers={APIAuthenticator.AUTH_HEADER: auth.get_authorization_header()})
if resp.status_code == 200:
    print(resp.json())
else:
    print('Error {}: {}'.format(resp.status_code, resp.text))

Node.js Example

The Form Submission API has a Node.js example.

Form Response API Python Automation

---

1. Not available with Business Starter and Plus accounts
2. Search by email address or phone number are delayed by up to fifteen minutes