Skip to main content
Contact Support

Merge Field Dos and Donts

Ryan J.
Updated

Merge fields are the foundation of your documents. In simple terms, they tell Formstack Documents where to merge information within your templates. Because they play such an important role, it’s important to follow a few key guidelines when building your templates.

 

The Basics

The correct format for a merge field is {$fieldName}.

Each merge field must start and end with curly brackets {} and include a $ immediately after the opening bracket.

When you close a merge field with a curly bracket, it will automatically convert into a pill-shaped field in the editor showing the field name.

 

Examples of acceptable merge fields:

  • {$name}
  • {$EmailAddress}
  • {$Home_Phone}

If you need to denote a space, use an underscore _ (for example, {$merge_field}).

  

✅ Do:

  • Start and end each merge field with curly brackets {}
  • Include a $ after the opening bracket
  • Use underscores to represent spaces
  • Use letters and numbers in your field name (but not at the start)

 

Examples:

  • {$merge}
  • {$Customer_ID}
  • {$OrderNumber}

  

🚫 Don’t:

  • Start a field name with a number
  • Use spaces in your field name
  • Use special characters such as /!@#$%^&*\
  • Use hyphens (-) in place of underscores

 

Examples of invalid formats:

  • {$1stName}
  • {$email address}
  • {$1234}
  • {$phone-number}
  • {$merge field}
  • {$merge/field}

  

💡 Tip:Keep your merge field names consistent across all connected systems (such as Formstack Forms, Salesforce, or your data source). Consistent naming ensures your fields map correctly and that your documents merge data without errors or extra setup.

 

Some extra considerations:

  • You can format your merge fields in a number of ways.  For examples on how to do this, please see the article Formatting Your Data.
  • You can combine multiple merge fields into a single merge field using Field Mapping.  An example would be if you had a merge field called {$First_Name} and a merge field called {$Last_Name}, but you wanted to combine them into a single merge field: {$Full_Name}.  Please see the article Field Map for more information on this useful feature.

Related articles