Form Responses by Dates API

Excel reports allow you to export form responses submitted between two dates as a spreadsheet. The Form Responses by Dates API returns the same results, but provides automated, programmatic access and sends data back in JSON format.

The Form Responses by Dates API

To look up¹ form entries submitted between two dates, insert the form's ID into the URL and submit a GET request:

API Response

If the request is successful, the API returns an HTTP 200 status and a JSON object with the form submissions.

• If the structure parameter is true, the API response has a fields attribute
• A list of form responses is accessible at api_response["entries"].
• If the form entry at index i has a form context value, it is included in api_response["entries"][i]["context"]["value"]
• If the form submission involved a payment, the amount, currency, processor name and transaction ID of the payment are available in a api_response["entries"][i]["payment"] object.
• As shown below, the value of upload and signature fields are JSON object. All other values are scalars.

Example

This is the API response for this form demo:

{
  "fields": [
    {
      "name": "Full Name",
      "id": 122619,
      "type": "name"
    },
    {
      "name": "Email",
      "id": 122620,
      "type": "email"
    },
    {
      "name": "Upload Your Picture",
      "id": 122621,
      "type": "upload"
    },
    {
      "name": "Comments",
      "id": 123744,
      "type": "text"
    }
  ],
  "entries": [
    {
      "entry": [
        "Nicky Smith",
        "nicky@example.com",
        {
          "type": "upload",
          "attachment_id": "fbfn",
          "filename": "Screen Shot 2022-04-27 at 2.43.32 PM.png"
        },
        ""
      ],
      "metadata": {
        "reference_number": "AE9IG131SWA4ZD90R454WWK6N",
        "date_submitted": "2022-05-01T15:43:08-07:00"
      }
    },
    {
      "entry": [
        "Mag Tan",
        "mag.tan@example.org",
        {
          "type": "upload",
          "attachment_id": "fc0p",
          "filename": "mag-picture-1.jpg"
        },
        ""
      ],
      "metadata": {
        "reference_number": "1WWTZYYKM4ZSHYS5CZZC6BIED",
        "date_submitted": "2022-05-03T01:39:48-07:00"
      }
    }
  ]
}

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 submit a form 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/forms/{}/entries/by/dates'.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)
            print('{} result(s)'.format(len(body['entries'])))
        else:
            print('Error {}: {}'.format(resp.status_code, resp.text))

if __name__ == '__main__':
    ApiTest().send_api_request(
        API_URL, start_date='2022-05-01', end_date='2022-05-10', structure='true'
    )

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.