Form Response API

The Form Response API allows you to retrieve an individual form response programmatically in JSON format or as a PDF document.

The API returns the same information you can get with a webhook.

The Form Response API

To look up a form response ¹, insert its Reference Number into the URL below 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 entry.

• If the structure parameter is true, the API response has a form (form metadata) and a fields attribute
• The form response is accessible at api_response["entries"][0]. This is for consistency with APIs returning multiple form submissions.
• If the form entry has a form context value, it is included in api_response["entries"][0]["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"][0]["payment"] object, for example: {'amount': '380.00', 'currency': 'USD', 'processor_name': 'paypal', 'transaction_id': '4XW287768B821925'}
• 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:

{
  "form": {
    "id": "lqh"
  },
  "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": [
        "Jane Doe",
        "jane@example.com",
        {
          "type": "upload",
          "attachment_id": "f8ud",
          "filename": "Capture.PNG",
          "presigned_url": "..."
        },
        "Hello, this is the picture for the project."
      ],
      "metadata": {
        "reference_number": "A3PG3EUJV27KZXJHC5TNK2CQI",
        "date_submitted": "2022-04-25T02:20:53-07:00",
        "ip_address": "1.1.1.1"
      }
    }
  ]
}

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 get a form entry in Python.

#!/usr/bin/env python3

import json
import requests
import config
from requests_oauthlib import OAuth1

REF_NUM = 'A3PG3EUJV27KZXJHC5TNK2CQI'
ENTRY_API_URL = 'https://formsmarts.com/api/v1/entries/{}'.format(REF_NUM)

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

if __name__ == '__main__':
    send_api_request(ENTRY_API_URL, structure='true', presigned_urls='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
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.

The Form Response PDF API

The Form Response PDF API allows you to export a form submission as a PDF document. The PDF generated is the same as the one you can get online and via the Download PDF link in email notifications.

To export up a form response as a PDF document ¹, insert its Reference Number into the URL below and submit a GET request:

Form Response API Python Automation

---

1. Not available with Business Starter and Plus accounts.