Introduction

Pre-filling is used to fill in one or more answers on behalf of respondents when they first load the form. That is, it fills those answers in before they possibly could, or pre-fills them.

Pre-filled answers do not necessarily need to be the answers the respondent ends up submitting.

For example, you might want to save the respondent some time when moving through a multi-form flow, where you would pre-fill some similar or duplicated fields on the next form by using answers from the first form. Or perhaps you have data from a CRM and want to provide a more personalized touch by pre-filling the information you already know about your user.

Throughout this guide, we'll cover:

  • how pre-filling works
  • the methods by which you can pre-fill a form
  • a more complex example where you pre-fill from form to form
  • pre-filling support by field type

How it works

Find a question's pre-fill key

To find a question's pre-fill key, enter the question's configuration by selecting the gear icon to the right of a question in the editor. Once the configuration is open, scroll to the bottom and find the section that indicates the pre-fill key.

How to find a question's pre-fill key

Alternatively, you can take advantage of answer piping's key resolution. When you {{ and then part or all of a question's title in a supported area on the form (body, question title, question help text, calculation, custom PDF, redirect URL, or integration mapping), a dropdown appears that shows questions that match the text you've typed.

Find a question's pre-fill key by using answer piping resolution

Later in this guide, we'll cover form-to-form pre-filling, where you can use answer piping to quickly and easily insert keys in a redirect URL.

Add a custom pre-fill key

Right below where you would find the generated pre-fill key in a question's configuration, there is a place for you to enter a custom pre-fill key. Then, where you would have used the generated key, you may use the custom key instead (e.g. name instead of abc123).

Assign a custom pre-fill key to a question

This is an optional feature.

Methods

Query string

Pre-filling, in most forms, is done by either by being a query string or by emulating the query string's format. In a URL, a query string is denoted by the segment of the URL after a question mark — ?. Subsequent key=value pairs are separated by an ampersand — &.

https://example.paperform.co?name=Danny

Above, the query string would be name=Danny as that's the portion after the ? in the URL.

Using our example data, our full URL using pre-filling would be similar to (line breaks added for clarity):

1 https://example.paperform.co?
2     name=Danny&
3     email=danny%40paperform.co&
4     phone=%28800%29+111-1111

Let's go through this line-by-line to help illustrate exactly what's happening.

Line 1: We use the URL of our form and denote the start of the query string with a ?.

Line 2: We set the field with a custom pre-fill key of name to the value Danny.

Line 3: We set the field with a custom pre-fill key of email to the value danny@paperform.co.

Line 4: We set the field with a custom pre-fill key of phone to the value (800) 111-1111.

What are all those funny-looking symbols in some of the values?

Put simply, URLs don't like certain characters and may break if you include them. To include certain characters, you can use something called percent-encoding, where a code represents a character, preceded by a %.

How do I use this URL?

  1. Use on Paperform directly

    Just paste it directly into your browser's address bar and go. It's automatically set up to work on our platform.

  2. Use on your own website (embedded)

    Follow the same procedure as above, but by adding the query string to the URL on the page where the form is embedded. You'll also need to add something to your embed code, which we'll cover in the next section.

Inheritance

When you embed a form on a website, the page that's doing the embedding is considered the parent and the embed — in this case, your form — is the child. Since the URL in your browser refers to the parent, pre-filling works slightly differently. Since the child looks to itself for the query string, it doesn't find it. However, this is easily solved: we can just inherit the query string from the parent, much like you might inherit money from parents.

To accomplish this, we need to modify the embed code slightly to include prefill-inherit as an HTML attribute. This signals to the embed that we want to pre-fill by inheritance.

Let's see what that looks like when we add it to some sample embed code:

<div prefill-inherit data-paperform-id="example"></div>
<script>
    (function() {
        var script = document.createElement('script');
        script.src = "https://paperform.co/__embed.min.js"; 
        document.body.appendChild(script); 
    })()
</script>

As seen above, all we had to do was add prefill-inherit as an attribute for our div.

Warning: Our forms are wrapped in an iframe. If you're using a site builder that wraps iframes in their own iframe, you will be unable to pre-fill by inheritance since the parent to the form will be the additional iframe the site builder adds instead of your actual page.

Static

When you pre-fill by using the query string on Paperform directly or by inheritance, we consider that dynamic pre-filling as it's subject to change. Alternatively, you can pre-fill using static values by pre-filling directly within the embed code so that the form is pre-filled the same way each time it loads.

Why would I use this over dynamic pre-filling?

  • Keep the URL cleaner by using no query string
  • Avoid having users modify the query string
  • Avoid users seeing the query string as easily
  • Use JavaScript on your website to set pre-filling

Warning: Users may still inspect the page's source code to see what you're pre-filling.

The static method uses the same format as the query string. In fact, you can set up the query string as you would for dynamic pre-filling and just cut and paste it for the value of the prefill attribute in your embed code instead.

Suppose we had a URL for pre-filling of

https://example.paperform.co?name=Danny&company=Paperform

where our query string is just

name=Danny&company=Paperform

We could set our embed code to be something like

<div prefill="name=Danny&company=Paperform" data-paperform-id="example"></div>
<script>
    (function() {
        var script = document.createElement('script');
        script.src = "https://paperform.co/__embed.min.js"; 
        document.body.appendChild(script); 
    })()
</script>

As we can see, all we did was take the query string and set it as the value to the prefill attribute on our div.

Now, every time the form is loaded, the name question would be pre-filled with Danny and the company question would be pre-filled with Paperform (assuming our custom keys matched those questions).

Dynamically pre-filling while using the static method

If you know some JavaScript, you can actually make the static method dynamic.

As an example use case, you might place one form on several different pages on your website and you want to know which page the form was submitted from. You may not want to use a query string or may not be able to reliably ensure it gets filled properly for every page. In this instance, you could use JavaScript to pull the current URL and then pre-fill a hidden field on the form so your submission data contains the page the user was on at submission time.

The exact implementation will vary greatly depending on use case and requires technical knowledge, but it roughly follows something similar to:

const someVariable = someData;
const form = document.querySelector("[data-paperform-id='form-id']");

form.setAttribute('prefill', someData);

In the above code, you'd want to make sure:

  • form-id is replaced by the form's actual ID or slug
  • someData contains key=value pairs in the same way the query string would for other methods

Generator (single-form)

If you're having trouble understanding how this plays out in practice or would like to play around, we have a simple pre-filling generator that lets you enter a form URL, some keys, and some values and then it shows you what the URL, with its query string, would look like.

Pre-filling from form to form

How it works

Suppose that you have two forms — Form 1 and Form 2 — with the following questions and keys:

Example data for pre-filling from one form to another

A user already enters their name on Form 1, so we don't want them to have to enter it again on Form 2. If we don't need it again on Form 2, we can just ignore this. However, if we want to tie submissions together or otherwise save the user time in filling out these details again on a follow-up form, we'd like to do this on behalf of the user seamlessly and automatically.

That's where pre-filling comes in. We can set up the redirect so that a question on Form 2 is pre-filled with the answer the user provided to the corresponding question in Form 1. We still follow the traditional key=value pair format of pre-filling (as described previously in this guide), but instead of setting a static value, we use answer piping to automatically replace the value with the answer the user provided when they submitted Form 1.

Continuing our name example and using the example data above, that means that we're interested in this piece in the query string:

name2={{ name1 }} 

which translates to, "For the name question on Form 2 (name2), set it equal to the answer for the name question on Form 1 ({{ name1 }})."

Throughout the remainder of the example redirect in the image, we can see that the same pattern continues — we set the key on Form 2 equal to the answer piped value of the corresponding question on Form 1.

Tip: It is not required that both fields on Forms 1 and 2 are of the same type. You can use a date question on Form 1 and then pre-fill a hidden field on Form 2, for example.

However, some fields do require that they be pre-filled with a specific format, which we'll cover in detail in pre-filling by field type below.

Additionally, you can combine answer piping with static values and use multiple piped values.

For example, your query string could look something like

details={{ name }}+works+at+{{ company }}+as+a+{{ role }}

to combine name, company, and role:

Danny works at Paperform as a Support Engineer

Generator (form-to-form)

If you'd like to play around with inserting your own keys to see how they affect the query string, check out our sample generator for form-to-form pre-filling. The title fields on that generator are not necessary but may help you better keep track of things.

Pre-filling by field type

Address

The format is

key=country,postal_code,state,city,street

You may elect to leave some fields blank when pre-filling, but you must still include all five (5) commas as if you were pre-filling all fields.

For example, to pre-fill just the postal code, you would do something like

key=,12345,,,

Appointment

We do not support pre-filling an appointment due to typically needing to check real-time availability.

Calculation

We do not support pre-filling calculations. To do something similar, pre-fill a hidden field and then reference the hidden field by its key in the calculation.

Color Picker

You may pre-fill a color picker by using its 3- or 6-digit hex color code, omitting the #.

Country

If you do not capture the full country name, pre-fill using the country's two-digit ISO code. The code must be in uppercase to count. If you capture the full country name, you must use the full country name for pre-filling.

Date

The format is yyyy-mm-dd regardless of the format set in your account or on the date field you're pre-filling. If the date you're using violates a restriction on the question (e.g. past or future dates only), the pre-filling will fail.

Email

To pre-fill an email field, a valid email must be passed. If an invalid email is passed, the pre-filling will fail. As a shortcut, you may use email as the key to pre-fill an email field instead of its actual key. However, this will pre-fill all email questions on the form.

If you're using an aliased email address (e.g. danny+prefill@paperform.co), you must use percent-encoding to encode the +. Otherwise, it will be interpreted as a space and the pre-filling will fail.

File Upload

We do not support pre-filling file uploads as the files are required to be uploaded to our servers first, which requires manually uploading the file(s) as an answer to that field.

Hidden

You may pre-fill a hidden field with anything. It's treated like a text field.

Image Upload

We do not support pre-filling image uploads as the files are required to be uploaded to our servers first, which requires manually uploading the file(s) as an answer to that field.

Multiple Choice

This follows the exact same rules as a dropdown.

Number

You may pre-fill a number field by passing a number. If the passed value does not meet one or more of the restrictions set in the field's configuration, the pre-filling will fail.

Phone Number

When pre-filling, any number entered will attempt to match the format (custom or otherwise) as best it can. That is, if you pre-fill (800) 123-123 for a U.S. phone number, it'll pre-fill everything but the last digit since that digit is missing. So, the pre-fill attempt won't be lost; it just won't be enough to pass validation necessarily in that case.

Note: The pre-filling format will override the custom format in terms of appearance. That is, for a U.S. format, the appearance is +1 (xxx) xxx-xxxx in the UI. If you pre-filling using 8001234567, your submission data will show exactly what you pre-filled without the parentheses and spaces.

Validation will still work as expected.

Price

You may pre-fill a price field with a number (whole or decimal).

If the price field's configuration has read only and disable prefilling for question enabled, you will be unable to use pre-filling for this field.

If you pass a value that has more than two decimal places, the value will be rounded to decimal places according to normal rounding rules.

Product

By passing the SKU, you may pre-fill product selections. If more than one product may be purchased, passing each SKU as a distinct key=value pair will select each product. Otherwise, it will select only the last product specified for pre-filling.

Products may not be created using pre-filling. You may only select products on behalf of the user that are available in the product question to begin with from editor configuration.

Note: You may not pre-fill product quantity.

Scale

You may pre-fill a scale field by passing the literal option. This must match an existing optional exactly or it won't have any effect. If you pass distinct values to the same scale field repeatedly, only the last value in the query string will be used.

Signature

You may pass a direct link to an image hosted somewhere. Do note that this will pre-fill the signature field with whatever image you use, even if it's not an actual signature.

Slider

You may pass a number to the slider field.

If the number passed is outside the range or does not follow the step in the configuration, the pre-filling will fail.

Subscription

You may pre-fill a subscription by its plan ID.

There are a couple of ways to find the plan ID:

  1. By using a visible calculation that checks {{ key.plans }} and then grabbing the ID when you select the plan on the live form
  2. By going to the platform where the plan lives and checking for an API ID or similar for the given plan

Text

You can pre-fill a text field with anything.

Time

The format for pre-filling a time field is xx:xx for both 12- and 24-hour configurations. If you use a 24-hour time for a field that's using 12-hour time, it will automatically set am/pm accordingly.

If you do not follow the format, unexpected pre-filling may occur.

URL

To pre-fill a URL field, you must use something resembling a URL. If you do not (e.g. you just pass peaches), the pre-filling will fail.

Yes/No

To pre-fill a yes/no, you must use the exact value of the options. That means "Yes" instead of "yes." Additionally, if a translation is applied that changes those values, you must use the translated values exactly instead or the pre-filling will fail.