How to Pre-Populate a Form

FormSmarts allows customers1 to pre-populate an online form by passing the value of input fields to the form's URL.

  • To populate the nth field, pass pf_n=the+value as a URL parameter
  • n is the index of the input field in the order fields appear on the form

Form Pre-Fill Example

In the example illustrated below, we've populated all the fields of a form by passing pre-fill parameters to it's URL:

https://formsmarts.com/form/xyz?mode=h5&pf_f1=Joe+Public&pf_f2=Green&pf_f4=yes&pf_f6=yes&pf_f7=Banana&pf_ro1=1&pf_s=l3T6cva8Ibxd2L0SOs-DaFcWIAk=

Pre-Populate a Form

  • For text boxes, like Field 1 above, set the prefill parameter to the value you want the field to be pre-populated with 2
  • For drop-down lists and radio buttons (e.g. Fields 2 and 7), set the prefill parameter to the value of the option you want to select
  • For checkboxes and items of a checkbox list, set the value of the prefill parameter to yes to check the corresponding box (Fields 4 and 6)
  • Checkbox lists are a bit tricky: the label “Field 3” and each individual checkbox in the checkbox list is considered here to be an individual field. So the label is Field 3, the first checkbox Field 4, the second checkbox Field 5 and the last one Field 6. Don't worry though, you can easily find out the index of a field and the name of its the pre-fill parameter with the Form API.

Any form can be pre-filled by providing field values in the form URL. This works “out of the box”; there is no need to activate this feature in your FormSmarts account.

Note that once a form was populated with data at least once, it can no longer be used without providing prefill parameters. This is to prevent someone from accessing the form at its base URL (e.g. https://formsmarts.com/form/xyz?mode=h5) and filling out all fields, including those intended to be pre-populated and made read-only.

Making an Input Field Read-Only

When populating an input field, you can specify that its value should not be changed by the user with the readonly pre-fill parameter pf_ro. For example, to make the first and third fields readonly, you would add pf_ro1=1 and pf_ro3=1 to URL parameters.

Set the readonly pre-fill parameter when you pre-populate a user ID (e.g. member ID, customer number) on a form. You can also make fields such as a person's name readonly to ensure they are not changed through the form.

Please try this election choice example.

Signing URL Parameters When You Populate a Form

As the receiver of a form submission, you can't trust that pre-populated values and readonly parameters have not been forged or tampered with unless prefill URL parameters are signed. The signature prevents the sender of a form or a third-party from modifying the values set by the form owner and go undetected.

Can I Populate a Form Without Signing Pre-Fill Parameters?

By default FormSmarts requires that pre-fill parameters contain a valid signature and rejects requests that are not signed or contain an invalid signature.

The signature allows FormSmarts to authenticate that the data was set by the form owner and ensures that the prefill values have not been tampered with, so we don't recommend pre-populating a form without signing the data.

If you want to pre-populate a form for the convenience of the user and do not care whether data is changed, you can use the Form API to allow unsigned pre-fill parameters.

Generating a Pre-Filled URL with the API Console

You can easily generate a prefilled URL with the API Console. This is a manual process, so this option is only suitable if you only need to create a small number of pre-filled URLs.

Generating a Pre-Filled URL Automatically

With the Form API

You can easily generate pre-filled URLs with the Form API. There are examples showing how to submit an API request in Python.

Creating a Prefilled URL on Your Website

The Node.js code below shows how to build the signature that needs to be passed to the pf_s parameter of a form's URL. You can use the code as is to create prefilled URLs, or as a reference to implement the signature algorithm with a different programming language.

  1. Fill your FormSmarts Pre-Fill Key and the ID of the form. The ID is shown in the form URL. For example xyz is the ID of form https://formsmarts.com/form/xyz?mode=h5.
  2. Create a list of key-value pairs, adding the form_id parameter
  3. Sort key-value pairs in lexicographic order
  4. URL-encode values1, so that Joe Public yields Joe%20Public
  5. Make a string like form_id=xyz&pf_f1=Joe%20Public&pf_f2=Green&pf_f4=yes&pf_f6=yes&pf_f7=Banana&pf_ro1=1, joining sorted key-value pairs with "&".
  6. Create a SHA-1 HMAC with your Pre-Fill Key and the string
  7. Encode the hash in URL-safe Base64, replacing "+" with "-" and "/" with "_".

If you need help implementing this in your preferred language, please feel free to contact us. 

const crypto = require("crypto");

// Get your Pre-Fill Key on https://formsmarts.com/account/view#security-settings
const preFillKey = "";

// The id in the form's URL, e.g. "xyz" for form https://formsmarts.com/form/xyz?mode=h5
const formId = "";

const params = {
    pf_f1: "Joe Public",
    pf_ro1: 1,  // Make field #1 readonly, so it's value can't be changed
    pf_f2: "Green",  // Input field #2 is drop-down list, select the "Green" option
    pf_f4: "yes",
    pf_f6: "yes",  // Field #6 is a checkbox, check it
    pf_f7: "Banana"
}

function normalizeParameters(parameters){
    /*
     * Normalize parameters into a utf-8 string of key-value pairs <key>'='<value> sorted in
     * lexicographic order and joined by "&".
     */
    var paramList = new Array();
    for (var key in parameters) paramList.push(
            {key: key.trim().toLowerCase(), val: parameters[key].toString().trim()}
        );
    paramList.sort(function(a, b){
        if (a.key < b.key) return -1;
        if (a.key > b.key) return 1;
        return 0;
    });
    // RFC2396 encoding allows: alphanumeric characters and - _ . ! ~ * ' ( )
    return paramList.map(function(p){return p.key + '=' + encodeURIComponent(p.val)}).join("&");
}

function buildSignature(parameters, key, formId){
    /*
     * Create the signature (pf_s URL parameter) allowing FormSmarts to verify that
     * the form pre-fill data passed to the form URL is authorized and wasn't changed.
     */
    var hmac = crypto.createHmac("sha1", key);
    parameters["form_id"] = formId;
    hmac.update(normalizeParameters(parameters));
    // URL-safe base-64: replace '+' with '-' and '/' with '_'
    return hmac.digest("base64").replace(new RegExp('\\+', 'g'), "-").replace(new RegExp('/', 'g'), "_");
}

console.log(buildSignature(params, preFillKey, formId));
  1. Currently only available with Business Max accounts and higher
  2. Values that may contain spaces, line breaks or special characters must be URL-encoded. All modern programming languages have URL-encoding functions or modules. FormSmarts uses RFC2396 encoding that allows alphanumeric characters and - _ . ! ~ * ' ( ). All other characters must be encoded.