How to Pass Form Data to Your Project

When a visitor submits a pop-up or embedded form, the data has to flow into the right places in your Maestra project — customer profile fields, action data, custom fields, and so on. This article explains how to map form fields to Maestra and how to choose between the two transmission methods.

​

How form fields work

Every input on the form has a system name — the key Maestra uses to identify the field when sending data. There are two kinds of fields:

• Standard fields (email, name, phone) come with built-in system names. You don’t have to assign them.
• Custom fields require you to set the system name yourself. The system name is what links the form input to a custom field on the customer profile or to a parameter on a customer action.

Field types you can add to a form:

• Text
• Date
• Number
• Dropdown
• Toggle buttons (single-select)
• Checkboxes (multi-select)

Some templates also expose extra fields specific to the template’s use case — for example, a “prize selected” field on a giveaway template, or a rating field on a feedback template.

​

Two ways to pass data to Maestra

You have a choice between a configuration-based approach and a code-based approach. Most teams should start with Basic steps and move to Custom JavaScript only when they hit a limit.

​

Basic steps

Use the form’s built-in action blocks to send data. No code, no pre-created actions. What you can do with basic steps:

• Create a new customer
• Update an existing customer
• Issue a customer action

How it works: in the form settings, you select the action you want and map each form field to the corresponding Maestra field via a dropdown. Maestra handles the data transmission for you. When to use it:

• You’re capturing standard customer data (email, name, phone, simple custom fields).
• You don’t need to run any logic on the data before sending it.
• You haven’t already defined a custom operation that you need to reuse.

​

Custom JavaScript

Use a pre-created Maestra operation and a JavaScript call to send data. More flexible, but requires more setup. What it adds beyond basic steps:

• Send data to any pre-defined operation, including ones that run complex logic.
• Reference any field on the form using percent-sign syntax.
• Compose data dynamically — concatenate fields, transform values, add conditional payloads.

How it works: you reference form fields and contextual values by wrapping their system names in percent signs. Examples:

• %email% — the email the visitor entered
• %name% — the name they entered
• %customs.fields_list.fieldname% — a custom field by its system name
• %utm_source% — the UTM source from the page URL

You compose a JavaScript payload using these placeholders and send it through an operation call to Maestra. The operation must already exist in your project. When to use it:

• You need to send data to a custom operation that has parameters basic steps don’t expose.
• You need to transform or combine fields before sending.
• You’re integrating with downstream systems that expect a specific payload structure.

​

Contextual data you can send

Beyond what the visitor types, Maestra exposes useful context you can include in either method:

• UTM parameters (%utm_source%, %utm_medium%, %utm_campaign%, etc.)
• Current page URL
• Visitor geolocation (when available)
• Form name
• Submission timestamp in ISO 8601 format

These can be attached to the customer profile, to the action being issued, or passed into a custom operation as parameters.

​

Configuration walkthrough

​

Basic steps example

You have a giveaway form with two fields: email and a “prize selected” dropdown. Maestra sends the data on submission, no JavaScript required.

​

Custom JavaScript example

Same form, but you want to send the data to a pre-created operation called WebsiteGiveawayEntry that also expects the page URL and UTM source. In the form’s Run custom JavaScript block, configure the call to your operation with these parameters:

• email → %email%
• prizeSelected → %customs.fields_list.prize_selected%
• pageUrl → %page_url%
• utmSource → %utm_source%

The operation receives the full payload and can use any of those values in flows, segments, or reports.