The Form Submission API endpoint allows FormSmarts customers to programmatically submit a form.

The Form Submission API

To submit a form programmatically1, insert the form's ID into the URL and submit a POST request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/entries
HTTP Method
POST
ParameterDescriptionNotes
field_id1, field_id2,… The name of the parameter to set the value of each input field of a form is the field's numeric ID. See next section. Optional for input fields which aren't mandatory on the form.
context Equivalent to the fs_ctxval form context parameter. Optional
Only allows alphanumeric characters and spaces.
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/xyz?mode=h5, its Form ID is xyz.

API Response

If the request is successful, the API returns an HTTP 200 response and a JSON object with the form entry's Reference Number:

{"reference_number": "DLNR3QPL2BZDZVKM37NSQF09X"}

If the request fails, the API returns a non-success HTTP status with a JSON object indicating the error:

{
  "message": "Invalid parameter: 510289, 510290.",
  "error_code": "invalid_param",
  "params": ["510289", "510290"]
}

Note: In some (rare) cases like if a server error occurs, the response body may contain plain text intead of JSON.

Implementation Note: Form Data Validation

When a user submits a form, FormSmarts validates their input and asks them to modify their entry if they provide invalid information.

Forms submitted via the API can only be accepted or rejected. If the data submitted is invalid, FormSmarts returns a HTTP 400 Bad Request error with a message, error code and a list of invalid parameters as illustrated above.

To reduce the chances of validation errors preventing successful requests:

  • Implement strong validation on the data you submit
  • Use general data types (e.g. Any Text instead of Letters Only) for general text input fields like people or company names
  • Do not use the general Any Text data type for structured data like email, phone, or URLs. Use the specific Email, Phone or URL type instead
  • Log all errors, i.e. any response with a HTTP status code different from 200.

Limitations

The following limitations apply to the Form Submission API:

  • E-Signatures are not supported
  • File upload is not supported at this time

Finding Input Field IDs

To find the ID of input fields of a form, log in to the API Console and submit a POST request to the API endpoint https://formsmarts.com/api/v1/forms/Form_ID/fields, as described in the Form API documentation.

For example, the screenshot below shows the IDs (right-most column) of the fields of the demo form used in the code example in the next section.

Finding the ID of a form input field

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

#!/usr/bin/env python3

import json
import requests
import config
from requests_oauthlib import OAuth1

FORM_ID = '24yc'
API_URL = 'https://formsmarts.com/api/v1/forms/{}/entries'.format(FORM_ID)

# Values of input fields of demo form https://f8s.co/24yc
FIELDS = {
    676771: 'Jane',
    676772: 'Doe',
    676776: 'blackhole@syronex.com',
    676773: '+1 (999) 999-9999',
    676777: '2021-08-23',
    676778: '15:35:30',
    676784: 'No, this is my first appointment',
    676796: '',   # This fields is optional, we can either submit and empty value or leave the field out
}

def send_api_request(fields):
    auth = OAuth1(config.FORMSMARTS_ACCOUNT_ID, config.FORMSMARTS_API_KEY)
    resp = requests.post(API_URL, data=fields, auth=auth)
    try:
        text = json.loads(resp.text)  # Response should be JSON
    except json.JSONDecodeError:
        text = resp.text
    if resp.status_code == 200:
        print('Reference Number of the form entry: {}'.format(text['reference_number']))
    else:
        print('Error {}: {}'.format(resp.status_code, resp.text))


if __name__ == '__main__':
    send_api_request(FIELDS)

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

Here is another code example in Node.js.

The only functional difference with the code above is that the Oauth 1 consumer key and secret are now defined in environment variable FORMSMARTS_ACCOUNT_ID and FORMSMARTS_API_KEY respectively.

const crypto = require('crypto')
const OAuth = require('oauth-1.0a')
const got = require('got')
const FormData = require('form-data')

const FORM_ID = '24yc';
const API_URL = `https://formsmarts.com/api/v1/forms/${FORM_ID}/entries`;

// Values of input fields of demo form https://f8s.co/24yc
const FIELDS = {
    676771: 'Jane',
    676772: 'Doe',
    676776: 'blackhole@syronex.com',
    676773: '+1 (999) 999-9999',
    676777: '2021-08-23',
    676778: '15:35:30',
    676784: 'No, this is my first appointment',
    676796: '',
}

function authHeader(fields){
    const oauth = OAuth({
        consumer: {
            // Get consumer key and secret from environment variables
            key: process.env.FORMSMARTS_ACCOUNT_ID,
            secret: process.env.FORMSMARTS_API_KEY,
        },
        signature_method: 'HMAC-SHA1',
        hash_function(base_string, key) {
            return crypto.createHmac('sha1', key).update(base_string).digest('base64');
        },
    });
    return oauth.toHeader(oauth.authorize({url: API_URL, method: 'POST', data: fields}));
}

function sendApiRequest(fields){
    (async () => {
        try {
            const resp = await got.post(API_URL, {
                body: formData(fields),
                responseType: 'json',
                headers: authHeader(fields)
            });
            console.log('Reference Number of the form entry: ' + resp.body.reference_number);
        } catch (error) {
            console.log(`${error.response.statusCode} ${error.response.body.message}`);
        }
    })();
}

function formData(object) {
    const formData = new FormData();
    Object.keys(object).forEach(key => formData.append(key, object[key]));
    return formData;
}

sendApiRequest(FIELDS);


  1. Not available with Business Starter and Plus accounts.