The Search API allows customers to lookup form responses by email address or phone number.

The Search API

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

  • To look up1 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.
API Endpoint
https://formsmarts.com/api/v1/entries/search
HTTP Method
GET
ParameterDescriptionNotes
query An email address or phone number Required
form_id A Form ID. If the URL of a form is https://f8s.co/1nk5, it's ID is 1nk5 Optional. If omitted, returns matches for all your forms.
limit The maximum number of form responses to return Optional. 50 by default.
offset An offset to return partial results, ie: 5 will return results 6 to the value of the limit parameter. Optional. 0 by default.

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 authenticates API requests with an OAuth 1 signature in the header.

Our OAuth 1 implementation relies on two tokens, a client key and a client secret:

  • Your Oauth 1 client key (also called consumer key) is your FormSmarts Account ID
  • Your Oauth 1 client secret (aka consumer secret) is your 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.

Oauth library are available for most programming languages.

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 requests_oauthlib import OAuth1

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

def send_api_request(endpoint, **params):
    auth = OAuth1(config.FORMSMARTS_ACCOUNT_ID, config.FORMSMARTS_API_KEY)
    resp = requests.get(endpoint, params=params, auth=auth)
    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__':
    send_api_request(API_URL, form_id=FORM_ID, query='example@example.com')

The code above imports Oauth authentication tokens form a config file, a Python module called config.py:

# Your Oauth 1 client key (also called consumer key) is your FormSmarts Account ID
# You'll find your Account ID on: https://formsmarts.com/account/view
FORMSMARTS_ACCOUNT_ID = 'FSA-999999'

# Your Oauth 1 client secret (aka consumer secret) is your FormSmarts API Key
# You'll find your API Key on: https://formsmarts.com/account/view#security-settings
FORMSMARTS_API_KEY = 'TqE35BBzxfmxC74YQ4jQCPFx1oKvFhECOfWrbTh8fVMG6viZWiTfvh4dOZSSK71v'

Node.js Example

The Form Submission API has a Node.js example.


  1. Not available with Business Starter and Plus accounts.