Guide
What merge fields are
Merge fields are placeholders that HighLevel swaps for real data at the moment a message is sent. Type {{contact.first_name}} in a text, email, workflow action or document, and each contact receives their own first name in its place.
They are what makes one template feel personal at scale. A single appointment reminder can greet every patient by name, show their own date and time, and give them their own reschedule link, all from one workflow action.
Every merge field follows the same pattern: two curly braces on each side, an object (who or what the data belongs to), a dot, and a key (which piece of data):
contact.— the person receiving the message.location.— your business, meaning the sub-account's business profile.user.— the team member assigned to the contact, or the user sending the message.appointment.andcalendar.— the booking that triggered the message.custom_values.— account-wide snippets you define yourself.
Keys are lowercase with underscores. {{contact.firstName}} or {{Contact.First_Name}} will not be replaced. The previewer flags these and suggests the correct version.
Custom fields vs custom values
These two sound alike but solve different problems, and mixing them up is one of the most common mistakes in HighLevel setups.
| Custom field | Custom value | |
|---|---|---|
| Belongs to | Each contact (or opportunity) | The whole sub-account |
| Example | {{contact.policy_type}} | {{custom_values.booking_link}} |
| Changes | Per person, from forms, imports or workflows | Once, in settings, and updates everywhere |
| Use it for | Data you collect about people | Links, prices, hours and phrases you reuse |
Custom values are a big time-saver. Put your booking link, review link, office hours and current offer into custom values, then reference them in every template. When the offer changes, you update one value instead of hunting through twenty workflows. Agencies that sell snapshots rely on this: the snapshot ships with custom values, and each client fills in their own.
To find the exact key of a custom field, open it in your settings or use the merge field picker in any message editor. HighLevel generates the key from the field name when you create it, so Policy Type usually becomes contact.policy_type, but renamed or older fields can differ.
Handling empty fields
A merge field with no data is replaced with nothing. That is fine in the middle of a sentence, but it breaks greetings: “Hi {{contact.first_name}},” becomes “Hi ,” for every contact without a first name, which is common for leads from ads, imported lists and missed calls.
There are three reliable ways to handle it:
- Branch in the workflow. Add an If/Else step that checks whether First Name is empty, and send a version of the message without the name on that branch. This is the cleanest option for important messages.
- Write copy that survives a blank. “Thanks for reaching out to {{location.name}}!” reads fine whether or not you know the name.
- Fill the gaps at the source. Make first name required on your forms, and clean imported lists before upload. The Contact CSV Cleaner splits full names into first and last name so the field is populated.
Use the preview above to test both cases: clear the sample first name and see how the message reads.
Where you can use merge fields in HighLevel
- SMS and email — in conversations, templates, bulk actions and workflow actions.
- Workflows — in message actions, internal notifications, task titles and webhook payloads.
- Funnels and websites — on pages a contact reaches after submitting a form, where HighLevel knows who they are.
- Documents and contracts — to prefill names, addresses and amounts.
- Calendar notifications — confirmations and reminders, where the appointment fields are available.
Appointment fields only have values when the message is tied to an appointment, for example in a calendar reminder or a workflow started by an appointment trigger. Used in a general bulk SMS, they come out blank.
Test before you publish
The previewer shows the structure of your message with realistic sample data, but real formatting depends on your account settings, especially for dates, times and time zones. Before you publish a workflow:
- Create a test contact with your own phone number and email, with every field you reference filled in.
- Create a second test contact with the first name left empty.
- Run both through the workflow, or send the template to both manually, and read what arrives on your phone.
It takes five minutes and catches the problems that otherwise go out to hundreds of contacts.
Frequently asked questions
What is the merge field for first name in HighLevel?
{{contact.first_name}}. For the full name use {{contact.name}}, and for the last name {{contact.last_name}}.Why is my merge field showing up as text instead of the contact's data?
How do I add a custom field to a message?
{{contact.your_field_key}}, replacing your_field_key with the key HighLevel created for that field. You can find it in the custom field settings or by picking the field from the merge field menu in any message editor.