> ## Documentation Index
> Fetch the complete documentation index at: https://help.maestra.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Steps>
  <Step title="Assign system names">
    Email uses the built-in `email` system name. For the dropdown, set the system name to `prize_selected`.
  </Step>

  <Step title="Open the post-submission settings">
    Go to **What happens after the form is submitted** and add an **Issue an action** block.
  </Step>

  <Step title="Pick the action">
    Choose the action defined in your project for giveaway entries — for example, **Entered summer giveaway**.
  </Step>

  <Step title="Map the fields">
    Map the form's `email` to the customer's email and `prize_selected` to the action's prize parameter.
  </Step>
</Steps>

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.

<Note>
  The custom JavaScript approach requires that the operation already exists in your Maestra project before the form can send data to it. Create the operation in **Settings → Operations** first, then reference it from the form.
</Note>

<Warning>
  System names must match exactly between the form and the destination. A typo in a custom field's system name will cause the data to be silently dropped — Maestra won't know which field to write to. After configuring the form, submit a test entry and verify the data lands where you expect.
</Warning>