About URL parameters

How it works

> Test it out

Setting up your form

Constructing your URL with parameters

> URL formatting

Parameters for embedded forms

Frequently Asked Questions


About URL parameters

Beacon's forms are already a versatile way for your supporters to submit information to you, but with adjustable URL parameters you can extend their functionality by:

  • Pre-selecting choices

  • Pre-filling information

  • Dynamically setting fixed data

This is useful in many different situations, and can be used for both standalone and embedded forms, but some of the most common are:

  • Pre-selecting a donation amount or membership type when someone has clicked a button or widget on another page

  • Setting a particular Fund or Campaign when a supporter has clicked your donate button from a different page on your website, or from an email

  • Pre-fill a supporter's name and email address by sending them a personalised link to a form


Note: This is an advanced feature and can have some complex parts. Your website developer will usually be able to help with many of these options!


How it works

URL structure

By adding extra elements to the normal URL that people visit to view your form you are able to dynamically set values when the form loads.

For example, a form's URL might usually look like this:

https://mycharity.beaconforms.com/form/c33c1c74

You then add a parameter to the end of the URL, such as this one which sets the default donation amount:

https://mycharity.beaconforms.com/form/c33c1c74?bcn_donation_amount=10

Multiple parameters can be added to pre-fill more than one value on the form, such as this one which sets both the donation amount as well as the chosen fund:

https://mycharity.beaconforms.com/form/c33c1c74?bcn_donation_amount=10&bcn_fund=123 

See our section on constructing URLs for more detail.

Form URL settings

Every form includes a 'URL Data' section where you can define the parameters you'd like to enable for that form.

Test it out for yourself!

All of the options below are the same form; the only differences are the URL parameters. Click each one and see how the form changes!

Base form:

https://beaconben.beaconforms.com/form/5da69de0

Pre-select the £50 donation option:

https://beaconben.beaconforms.com/form/5da69de0?bcn_donation_amount=50

Pre-fill the 'Families in Need' fund:

https://beaconben.beaconforms.com/form/5da69de0?bcn_fund=1331

Pre-fill name and email address:

https://beaconben.beaconforms.com/form/5da69de0?bcn_first_name=Ben&bcn_last_name=Cook&bcn_email=ben%40beaconcrm.org

Combined:

https://beaconben.beaconforms.com/form/5da69de0?bcn_first_name=Ben&bcn_last_name=Cook&bcn_email=ben%40beaconcrm.org&bcn_donation_amount=50&bcn_fund=1331


Setting up your form

Once you've finished designing your form and the questions you'd like to ask on it, you can then configure the different URL parameters that you'd like to use.

Fixed parameters

All forms have some fixed parameters that are always available. The options will vary by form type:

  • First name (All forms)

  • Last name (All forms)

  • Email address (All forms)

  • Donation amount (Donation, Event registration, Membership)

  • Donation frequency (Donation, Event registration, Membership)

  • Membership type (Membership)

  • Membership frequency (Membership)

  • Membership annual frequency type (Membership)

Optional parameters

For any other values you can choose both which fields you'd like to be able to set data in, as well as what the parameter itself looks like in your URL. When changing the name of your parameter:

  • You can use letters, numbers, and underscores only

  • The parameter does not need to be unique. For example, on a donation form, you could configure a bcn_fund parameter on both the 'Payment' and 'Subscription' record types (it would set the same value in both), or you could configure a bcn_payment_fund and a bcn_subscription_fund parameter if you wished to be able to distinguish between the two.

If the field you've chosen is a question on the form, any data in your URL parameter will pre-fill that question (but can be changed by the submitter).

If the field you've chosen is not a question, the data will instead be used as fixed data and be set behind the scenes for that submission (cannot be changed by the submitter).

Note: Not all field types can be set using URL parameters. See the list of fields here.


Constructing your URL with parameters

There's a particular format that your URLs will need to use to make sure your parameters work correctly with your form.

Tip: Want help building your URL? Use our handy tool here!

There's 3 rules you'll need to follow:

  1. Separate the parameters from the base URL

  2. Separate multiple parameters from each other

  3. Format parameter values correctly

1. Separate the parameters from the base URL with a '?'

At the end of your page or form URL, insert a question mark ? before the first parameter:

2. If you have more than one parameter, add '&' to separate them

After the end of one parameter, and before the start of the next, add an ampersand & to divide them from each other:

3. Format the values of your parameters correctly for a URL

After each parameter you want to add, you'll need an equals sign = and then the value you want to use in your form:

How you enter/format the values will vary a little for each parameter. Read on for value formats!

Donation parameter formatting

Donation amount

The value can be any number

Example: bcn_donation_amount=100

Donation frequency

The value should be one of the frequencies enabled in the donation section of your form, and would be any of single, monthly or annual

Example: bcn_donation_frequency=monthly

Note: You should set both an amount AND frequency if you'd like to pre-select an option on your form. Both parameters must be set for 'Additional donation' sections on Event or Membership forms.

Membership parameter formatting

Membership type

The value should be the same text as one of the membership types on your form (not case sensitive)

Example: bcn_membership_type=family

Note: If a membership type is longer than one word, or
includes special characters, it will need to be encoded
(aka: changed into URL accepted characters). See our FAQ.

Membership frequency

Use if your membership has more than one frequency option. The value should be either monthly, annual or lifetime

Example: bcn_membership_frequency=annual

Membership annual frequency type

Use if your annual membership allows both regular and one-off payments. The value should be either single or regular

Example: bcn_annual_frequency_type=regular

Field parameter formatting

Short text / First name / Last name / Email

The value can be any text up to 255 characters

Example: bcn_apple_thoughts=I%20love%20apples

Note: When adding text to a URL, many characters need to be encoded
(aka: changed into URL accepted characters). See our FAQ.

Organisation name

If you've asked a question for an Organisation name as short text, follow the short text parameter above.

If you've asked a question for an Organisation name as a list of records, or haven't added it as a question, follow the point to another record parameter below.

Checkbox

The value can either be true or false
Example: bcn_likes_apples=true

Dropdown list

The value should match one of the options in the field
Example: bcn_apple_variety=gala

If multiple options are allowed, separate them with a comma

Example: bcn_apple_varieties=gala,pink%20lady

Note: If a dropdown option is more than one word, or
contains special characters, it will need to be encoded
(aka: changed into URL accepted characters). See our FAQ.

Point to another record

The value should be the Record ID of the record to link to

Example: bcn_apple=1754

If multiple options are allowed, separate them with a comma

Example: bcn_apples=1754,2553,311


Parameters for embedded forms

There are two ways to use parameters with embedded forms:

  1. URL parameters

  2. Add parameters to form embed codes

URL parameters for embedded forms

If you've embedded a form in your website, you can still use URL parameters in the same way that you'd use them for standalone forms.

Simply add your parameters to the page's URL, and your form will be able to read them!

For example:

Goodheart Animal Sanctuary

Goodheart have an animal adoption form here:

https://www.goodheartanimalsanctuaries.com/adopt/animal-adoption-form/

We can use URL parameters to pre-select the 'Adoption - Standard' option, and pre-filling Biscuit the goose as our adopted animal, like this:

https://www.goodheartanimalsanctuaries.com/adopt/animal-adoption-form/?bcn_c_ani
mal=15&bcn_membership_type=Adoption%20-%20Standard

Arnos Vale Cemetery

Arnos Vale have a donation form here:

https://arnosvale.org.uk/donate/

We can use URL parameters to set a custom £200 donation amount, and pre-fill a donor's details, like this:

https://arnosvale.org.uk/donate/?bcn_first_name=Ben&bcn_last_name=Cook&bcn_email 
=ben%40beaconcrm.org&bcn_donation_amount=200

Friends of Bude Sea Pool

Bude Sea Pool have a membership form here:

https://www.budeseapool.org/join-us/

We can use URL parameters to pre-select the 'Family' membership type, and pre-fill the member's details, like this:

https://www.budeseapool.org/join-us/?bcn_first_name=Ben&bcn_last_name=Cook&bcn_e
mail=ben%40beaconcrm.org&bcn_membership_type=Family

Add parameters to form embed codes

If you have a form appearing in multiple places on your website, you can also add parameters directly to the embed code instead of using (or in conjunction with) URL parameters.

For example:

The embed code for a donation form might look like this:

<div class="beacon-form" data-account="beaconben" data-form="5da69de0"></div>

We can add parameters into the code to pre-set or pre-fill data just like with the URL parameters.

If we wanted to set the monthly £10 amount for this particular placement of the form, we could include that in the code:

<div class="beacon-form" data-account="beaconben" data-form="5da69de0" data-bcn-
donation-amount="10" data-bcn-donation-frequency="monthly"></div>

Parameters in embed codes are constructed slightly differently from their URL counterparts. Here's how to format them:

  1. Change underscores _ to hyphens -

  2. Prefix the parameter with data-

  3. Place the value in double quotes " "

Unlike URL parameters, you won't need to encode any text or symbols within your values as long as they're inside the double quotes.

For example:

A URL parameter to set a short text field might look like this:

bcn_apple_thoughts=I%20love%20apples%21

When placed in an embed code it should be changed to this:

<div class="beacon-form" data-account="beaconben" data-form="5da69de0" data-bcn-
apple-thoughts="I love apples!"></div>

If you have any fields where you want to set multiple values, such as a multi-select dropdown list or a point to another record field that can point to multiple records, you can comma separate that values within the parameter:

<div class="beacon-form" data-account="beaconben" data-form="5da69de0" data-bcn-
apple-varieties="gala, pink lady, fuji"></div>
<div class="beacon-form" data-account="beaconben" data-form="5da69de0" data-bcn-
apples="1754,2553,311"></div>


Frequently asked questions

How do I adjust text with spaces or other characters for short text / dropdown list / name / email parameters?

There are many characters that URLs don't support that you'll want to include in your parameter values - most commonly spaces!

For example, this would not be part of a valid URL:

bcn_apple_thoughts=I love apples!

I love apples! would need to be changed to I%20love%20apples%21

bcn_apple_thoughts=I%20love%20apples%21

The easiest way to convert it is to use a URL encoder such as this one; simply copy and paste your text. Alternatively, if you'd like help building your URL, we've also created a handy tool here that lets you put all your components together into a full URL.

Which fields can we use URL parameters for?

  • First name

  • Last name

  • Email address (the default Person field, not all email address fields)

  • Short text

  • Dropdown list

  • Checkbox

  • Point to another record (using the Record ID of record to point to)

See how to set values for each field type here.

If there's another field type that you'd like to use URL variables for, do let us know your use case so that we know what's useful!

What happens if I don't set a valid value in a URL parameter?

Nothing! We'll ignore any invalid URL parameters so your form will be able to be submitted as usual.

What happens if I use a URL parameter that isn't in the form's settings?

Nothing! We'll ignore any parameters (even if valid) if they haven't been added in your form's settings. This means someone can't deliberately set fixed data for their submission that you hadn't intended to be set!

In an embedded form, what happens if I use the same parameter in a URL and embed code?

We'll give the URL parameter the priority, so if you've set 'Fund A' in your embed code, but 'Fund B' in your URL, 'Fund B' would be used.

Did this answer your question?