Pre-filling Guide

Select a question in the editor to open its configuration on the right. You will find the ID at the very top of each config menu.

Alternatively, you can take advantage of answer piping's ID resolution. When you type {{ 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.

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.

At the bottom of any question's configuration, there is a place for you to enter a custom ID. Then, where you would have used the generated ID, you may use the custom ID instead (e.g. name instead of e7jcq).

This is an optional feature.

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 question ID of name to the value Danny.

Line 3: We set the field with an ID of email to the value danny@paperform.co.

Line 4: We set the field with an ID 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.

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.

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 IDs 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

A special case applies for popup forms that are called programmatically. Namely, objects are used instead to pre-fill instead of the traditional key=value pairs. They're still pairs, but they follows a key: 'value' pairing instead.

Note: This section does not apply to popup forms that are not called programmatically.

Continuing our trend of static and dynamic pre-filling, here's how you'd accomplish that using programmatically-called popup forms:

Static

Paperform.popup('form-id', { prefill: { key1: 'value1', key2: 'value2' }});

Dynamic

Paperform.popup('form-id', { prefillInherit: true });

The general concepts from previous sections apply here as well. The notable exception is, as mentioned previously, that the format is slightly different since we're calling a function instead of setting HTML attributes directly.

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 question IDs, and some values; and then it shows you what the URL, with its query string, would look like.

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

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 Senior Support Engineer

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.

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

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

We do not support pre-filling calculations. To do something similar, pre-fill a hidden field and then pipe the hidden field's answer into the calculation.

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

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.

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.

You cannot arbitrarily set any value for a dropdown; rather, you can select an option that exists within the options set in the editor for this field.

There are two ways to pre-fill a dropdown:

1. Pass the literal options repeatedly as if they were separate answers
2. Pass the position of the option in the list (e.g. the second option is in the second position)

As an example, these two ways would look something like

1: key=option1&key=option2
2: key=--2--

Support for selecting multiple options at once is determined by the field's configuration. If you try to pass multiple options for a field that is not configured to accept more than one answer, the last option in the query string will be the option chosen for that field.

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.

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.

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

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.

A matrix may be pre-filled by using spreadsheet-style notation to refer to specific “cells” as column-row pairs. The first column is A and the first row is 1.

That is, if you want to pre-fill the third option in the second row, you would use C2. The third option in a specific row would be in the third column, which corresponds to C and the second row is represented by 2.

If you want to pre-fill multiple options, you may separate each column-row pair by a comma.

For example, if you wanted to pre-fill

• the second option in the first row
• the fourth option in the second row
• the first option in the third row
• the third option in the fourth row

then you would use

key=B1,D2,A3,C4

This follows the exact same rules as a dropdown.

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.

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 are 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.

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.

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.

You may pre-fill a rank field as you would a multiple choice or dropdown field.

The order in which you use the options will be the rank in which those options are set when pre-filled.

That is, if you use something like

https://example.paperform.co?rank=A&rank=D&rank=E

then the field will have options A, D, and E ranked 1 through 3, respectively.

If you are not ranking all items, a minimum is set, and you attempt to pre-fill using less options than the minimum, pre-filling will fail.

You may pass a whole number to pre-fill a rating field.

If the number is lower than 1 or greater than the maximum rating, the pre-filling will fail.

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.

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.

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.

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

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

1. Use a visible calculation that checks {{ question_id.plans }} and then grab the plan ID when you select the plan on the live form.
2. Go to the platform where the plan lives and check for an API ID or similar for the given plan.

You can pre-fill a text field with anything.

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.

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.

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.