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 up1 form entries submitted between two dates, insert the form's ID into the URL and submit a GET request:

API Endpoint
HTTP Method
start_date Start date in ISO 8601 format, e.g. 2020-12-30 Required
end_date End date in ISO 8601 format, e.g. 2020-12-31 Optional, defaults to the current date if omitted
structure Set to true to include the form structure (list of input fields with their name, ID and data type) and metadata (form ID) in the API response. Optional, true or false, defaults to false.
presigned_urls Set to true to include pre-signed URLs in the API response so you can automatically retrieve the form uploads and eSignatures associated with a form submission. Pre-signed URLs are only valid for a few minutes. Optional, true or false, defaults to false.
timezone Timezone used for dates in the API response, for example America/Los_Angeles. Timezones are listed here. Also defines the timezone of the start_date and end_date parameters. Optional. If missing, we use the timezone of your account or UTC if no timezone is set.
The ID of a form is the alphanumeric string in its FormSmarts.com URL. For example, if a form's URL is https://formsmarts.com/form/2xyz, its Form ID is 2xyz.

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.


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",
          "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",
          "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:


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 submit a form 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/forms/{}/entries/by/dates'.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)
        body = json.loads(resp.text)  # Response should be JSON
    except json.JSONDecodeError:
        body = resp.text
    if resp.status_code == 200:
        print('{} result(s)'.format(len(body['entries'])))
        print('Error {}: {}'.format(resp.status_code, resp.text))

if __name__ == '__main__':
        API_URL, start_date='2022-05-01', end_date='2022-05-10', structure='true'

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

# 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

Node.js Example

The Form Submission API has a Node.js example.

  1. Not available with Business Starter and Plus accounts.