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.

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

Example

This is a sample API response:

[
   {
      "reference_number":"1GZCTWIGK8E5HYPIK0RPMIJT7",
      "date_submitted":"2017-04-29 03:22:21",
      "form_id":"1nk5",
      "form_name":"E-Signature Demo"
   },
   {
      "reference_number":"94JSBKMURKW3UTOMVGA0SPWLK",
      "date_submitted":"2017-04-26 11:17:50",
      "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

Let's wrap this up with an example showing how to search form responses matching an email address in Python:

#!/usr/bin/env python3

import json
import requests
import config
from formsmarts_api import APIAuthenticator

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

class APITest:

    def __init__(self):
        self._au = APIAuthenticator(config.FORMSMARTS_ACCOUNT_ID, config.FORMSMARTS_API_KEY)

    def get_headers(self):
        return {APIAuthenticator.AUTH_HEADER: self._au.get_authorization_header()}

    def send_api_request(self, endpoint, **params):
        resp = requests.get(endpoint, params=params, headers=self.get_headers())
        try:
            body = json.loads(resp.text)  # Response should be JSON
        except json.JSONDecodeError:
            body = resp.text
        if resp.status_code == 200:
            print(body)
        else:
            print('Error {}: {}'.format(resp.status_code, resp.text))

if __name__ == '__main__':
    ApiTest().send_api_request(API_URL, form_id=FORM_ID, query='example@example.com')

The code above imports your account credentials from a config file, a Python module called config.py:

# You'll find your Account ID at: https://formsmarts.com/account/view
FORMSMARTS_ACCOUNT_ID = 'FSA-999999'

# You'll find your API Key at: https://formsmarts.com/account/view#security-settings
FORMSMARTS_API_KEY = 'TqE35BBzxfmxC74YQ4jQCPFx1oKvFhECOfWrbTh8fVMG6viZWiTfvh4dOZSSK71v'

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