ONTRAPORT Pages v3 ("Pages") can parse variables added to the URL. These variables can be used to populate merge fields on the page or fill in Pages native forms. The variables work on SSL Pages as well as non-SSL Pages.
URL variables are also called "URL query strings" or "URL parameters". Here's an example using the first name and last name "Jack Spratt":
The standard format is to have a question mark at the very beginning of the variables as shown above. Then, each variable has a label or identifier, an equals sign and the value for the variable. Multiple variables can be added by separating them with an ampersand, as shown above. Note that the identifiers for first and last name match our merge codes without the brackets - [First Name] and [Last Name] with the spaces represented by a plus sign.
Note: This feature does not populate fields in an ONTRAform used on the Page. Only native Pages forms, created in the Pages editor, can receive the values.
Why Use URL Variables
- It's the only way to merge data from the contact record onto secure pages. So, if you want to send someone to an order form and put their name (or whatever) on the page to personalize it, then you'll use this feature.
- You can pre-fill form values, to make it easier for your people to submit forms and order forms. Again, for secure pages, this is the only way to do this.
- Coming soon: Internal referral tracking! Say you want to track which of your sales reps drove an online sale. You may not want to put them in your affiliate/partner program because that would mess up referral tracking. So, you need a different way to track it. One way would be to have your reps send their prospects links with their id or name in the url: www.yoursite.com?salesrep=Jenny. Then, you can use that salesrep variable to prefill a hidden field on your order form. (Note: hidden fields coming to Pages very soon!)
Passing Variables From ONTRAforms or Legacy Smart Forms
URL variables cannot populate a legacy Smart Form or ONTRAform, but these forms can send the information they collect to a Page. Set the Page as the "Thank You" page for the form. Then, in the form's settings check the "Pass CGI variables to the Landing / Thank you page".
The field data collected on the form will be added to the Thank You page's URL. ONTRAPORT formats the URL with the variables as shown below.
CGI variables use the proper field names from the API. To populate them in a merge field on the page or in a hidden Page's form on that page use the same field name in brackets. Here are some common ones.
|Field Name||CGI Variable||Merge Field|
To see all the field names in your account, including custom fields, you can enter an API Key and APP ID number from Administration > Integrations > ONTRAPORT API Instructions and Key Manager into the interactive Live API Tool. Scroll down to Contacts and click to expand it, then click on the Get /Contacts button (fourth from the top of that section). Leave all the settings at the defaults and click the "Try it Out" button near the bottom. The "Response Body" that appears after a few minutes will list all the contacts with the API field names for each field.
Passing URL Variables in an Email Link
You can build the URL variables for links in email and on Pages. Add the URL variables after the base URL in the link editor. The format is an identifier for the field, an equals sign, and the value. The value can be a literal string or a merge field. You can use standard merge fields for the value if sending the email from ONTRAPORT.
Start the variables with a question mark after the base URL and use an ampersand between the variables.
?First+Name=[First Name]&Last+Name=[Last Name]
Remember that the URL variables are appended to the base URL, as shown here:
https://ontraport.com?First+Name=[First Name]&Last+Name=[Last Name]
Note: Do not convert the spaces in an ONTRAPORT merge field with brackets, as ONTRAPORT will take care of populating the merge field and applying the necessary encoding.
If you are sending a literal string with spaces, convert the spaces to either a plus sign or %20 as shown here between "von" and "Mises" in the last name. This is the same technique as using the plus sign for creating identifiers from merge codes without brackets:
Prefill Form Fields on Secure Pages (SSL)
The variables you pass in the URL can prefill the Page's Smart Form and Order Form fields. Use the field name as the identifier in the URL. The field name is "First Name" in this example.
Then, use the the same field name in the form field as the Placeholder, with brackets.
The URL will prefill this First Name field with "Jack" because the field name in brackets - [First Name] - matches the identifier in the URL variable.
SSL pages cannot use the standard merge codes to prefill form fields.
Remember, this limitation is only on the secure page's side. If you are sending the link to the secure page using an ONTRAPORT email you can still use the merge field to build the URL variable. It is the identifier that must be the field name alone, without brackets, in the URL. Both of these URLs would prefill the First Name field on our order form:
Populating Hidden Form Fields
Forms created on Pages can have hidden fields. You specify them in the Form Settings. A hidden field can be nearly any Contact Record field including custom fields. Hidden fields do not appear on the form, and are not shown to the Contact during or after the form processing.
To populate the hidden field you can use merge fields. In this image we have the custom field "Owner of value" set to be populated with the [First Name] merge field. Merge fields can be selected using the merge field drop down arrow icon.
You can also use values you pass to the page via the URL. This can be useful when you want to mask the reason for the value being passed. For example, you may want to pass a Last Referrer name without using that term. Using an ad hoc merge field such as "friend" in the URL might have something like this appended to the page URL: ?friend=Thomas+Jefferson.
[friend] is now an ad hoc merge field, and can be used to populate the Last Referrer field in the form's hidden fields. "Thomas Jefferson" would be populated into the Last Referrer field.
Things to remember about hidden fields:
The value you pass into the hidden field must match the field type. For example, text for text fields, numbers for numeric fields and dates for date fields. Dates in hidden fields use the MM/DD/YYYY format regardless of your account settings.
Some fields are not available in the drop down. For example, drill down fields in the Contact Record, such as the WordPress Websites field where you "drill down" to select one of several WordPress websites, and multi-value fields using drop down or list selection do not appear in the drop down because they cannot be used as hidden fields.
Usecase: Google gclid Parameters
Google Click Parameters are added to the URL of Google Ads. If you have a Google ad leading to one of your Ontraport Pages you can capture the "gclid" parameter in a custom text field. When you view the "gclid" parameter in the url you will notice it is in the format "gclid=1234567890" where the numbers are a random string. Create your custom field as a text field, include it in the Page's form settings as a hidden field, and use the "gclid" portion of the parameter as an adhoc merge field. In this image we have the custom field named "Custom gclid value" specified as a hidden field, and the [gclid] ad hoc merge field.
Populating Merge Fields on the Page
Standard ONTRAPORT merge fields will populate with the URL variables if the identifier is a field name. Inserting the [First Name] merge field on the Page, then passing a URL variable ?First+Name=Jack will have the merge field replaced with "Jack". Standard merge fields "disappear" if not filled.
Ad Hoc Merge Fields
You can create your own merge fields that don't require a field in the Contact or custom object record. Specify them in the URL variable and then have the same name in brackets on the Page. "?New+Merge+Field=This+is+new" would populate a merge field [New Merge Field] on the page with "This is new". However, if the variable is not passed by the URL the merge field is displayed in plain text on the page as [New Merge Field]. Ad hoc merge fields do not disappear if not populated like standard merge fields do.
- URL variables take precedence over PURLs and cookie data. This allows them to be used for secure landing pages.
- Caution: Passing a literal "?First+Name=Jack" URL variable to Page with a Smart Form to prefill it will, upon submission, change the Contact's first name to "Jack".
- Use ONTRAPORT merge fields where possible.
- Normal ONTRAPORT merge fields will "disappear" if not populated, so "Hi [First Name] -" becomes "Hi -" if no value is passed for the First+Name field.
- Ad hoc merge fields are always displayed. If no value is passed, they will show the original value such as [New Merge Field].
URL variables are not secure when passed to a non-SSL (HTTP) page. When passed to a page protected by SSL the entire URL is encrypted, but may be stored in plain text form in server logs. We do not recommend sending personal information via URL variables.