Every Marketo field has a Friendly name, a Token name, a Form Field name, a REST API name, a SOAP API name, and a Velocity name — and they may all be different

Feels weird to be writing about this at such a late date, but there’s misinformation going around, perhaps AI-influenced.

The spur for this post was the erroneous claim that Marketo Forms 2.0 uses REST API names as Form Field names. That is, if the REST API name is email the corresponding form field is <input name="email">.

That’s clearly untrue, as you can see by inspecting the HTML of a basic form:

But even the response I gave on the Nation — No, it uses the SOAP API name — isn’t true 100.00% of the time. Don’t get me wrong: it’s true enough to get you through 99.99% of scenarios, and infinitely true-er than the false claim about the REST API name. It’s certainly true for the system field that holds the lead’s email address, i.e. the one with the default Friendly Name Email.

The truly-true statement is “Marketo uses the Form Field Name as the Form Field Name.” The tautology illustrates that it’s possible for the <input name> attribute to be completely decoupled from any other metadata about the field.

So how many names can a field have?

Each field has 6 possible names, each for a different context:

• the Friendly Name, used in Field Management and in (most) dropdown lists
• the Token Name, used to output field values in Emails, LPs, webhooks, or flow steps
• the Form Field Name, used as the name attribute on form elements
• the REST API Name, used in the modern REST API
• the SOAP API Name, used in the defunct SOAP API
• the Velocity Name, used when you pull the field into the Velocity context (i.e. check the field in Script Editor)

Some of those names may be identical for a given field. For example, the built-in Email field has:

• Friendly Name Email
• Token Name Email Address (i.e. {{lead.Email Address}})
• REST API Name email
• Form Field Name Email
• SOAP API Name Email
• Velocity name Email (i.e. $lead.Email)

So there are only 3 unique values across the different types. But sorry to say, you must consider that a coincidence. As noted above, it’s not 100.00% safe to assume the Form Field Name is the SOAP API Name.

Check out this interesting exception, the built-in (and, to be fair, largely unused) field with the Friendly Name Marketo Data.com ID:

• Friendly Name Marketo Data.com ID
• Token Name Jigsaw Contact ID ({{lead.Jigsaw Contact ID}})
• REST API Name jigsawContactId
• Form Field Name JigsawContactId
• SOAP API Name Marketo Jigsaw Contact Id
• Velocity Name: Marketo Jigsaw Contact Id ($lead["Marketo Jigsaw Contact Id"])

Not only does this field have 5 unique values, the Velocity Name is notable because when you drag the field from the tree in Script Editor, Marketo inserts ${lead.Marketo Jigsaw Contact Id}. This is actually invalid VTL because spaces aren’t allowed in dot-property format, just like in JavaScript. You’ll get a ParseException if you leave it like that.[1]

Also notable: the SOAP API Name has spaces. That means the SOAP API Name and Form Field Name must be different. Not that an HTML <input name> can’t have spaces, standards-wise — it certainly can — but an HTML <input id> can’t have spaces and Forms 2.0 uses the same value for name and id. (This is good, by the way.)

Don’t be scared, just treat each one separately

This isn’t a big deal, really. Just give up your assumptions about the connection between names.

• When you use the token browser, Marketo always inserts the right Token Name. Don’t copy-and-paste the Friendly Name.
• Inspecting the HTML <form> or running getValues() shows the Form Field Name. Don’t copy-and-paste the SOAP API Name. (Or go ahead and paste it because it’s the same 99.99% of the time, but check there first if anything goes wrong!)
• When you drag the field onto the Script Editor canvas, Marketo always inserts the right Velocity Name.
• The REST API Name is easy to get from Field Management or the Describe Lead API endpoint. Don’t assume it’s the same as the Friendly Name, even if the Friendly Name has an API-compatible format (no spaces or non-ASCII characters).

Notes

[1] Instead, you need to change it to $lead["Marketo Jigsaw Contact Id"] or $lead.get("Marketo Jigsaw Contact Id").