Using placeholders

<body>
<p id="docs-hc-snippet" style="display: none;">Placeholders are references to ticket, user, andcustomdata that you include in the subject and body of email notifications. Without them it would be impossible to create automated messages. When you specify placeholders, remember they are case sensitive. For the complete list of placeholders seePlaceholder reference for business rules.</p>
<div class="article-banners">
<div id="docs-wmp-link">
<a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener" target="_blank">What's my plan?</a>
</div>

<div class="article-banner" id="suite_all">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>

<div class="article-banner" id="support_all">
<table>
<tbody>
<tr>
<td>
<strong>Support</strong>
</td>
<td>Team, Professional, or Enterprise</td>
</tr>
</tbody>
</table>
</div>

</div>
<div id="docs-ai-summary">
<p id="docs-ai-summary-toggle">Summary: <span id="up-triangle">◀</span><span id="down-triangle">▼</span></p>
<p id="docs-ai-summary-content">Placeholders let you include ticket, user, and custom data in email notifications, macros, and business rules to automate messages. You can reference custom fields, including drop-downs and lookup relationships, to pull related record data. Use Liquid markup with placeholders for advanced customization like multi-lookup fields and checkboxes. Placeholders are case sensitive and support dynamic content based on ticket context.</p>
</div>

<div class="body">

<p class="p">Placeholders are references to ticket, user, and <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5914453843994" target="_blank">custom</a> data that you include
in the subject and body of email notifications. Without them it would be
impossible to create automated messages. When you specify placeholders,
remember they are case sensitive. For the
complete list of placeholders see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408886858138" target="_blank">Placeholder reference for business rules</a>. </p>
<p class="p" dir="ltr">Support includes <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408894213018" target="_blank">system ticket rules</a> that
suppress placeholders in ticket triggers in certain situations. System
ticket rules are predefined rules that you cannot change, modify, or
override, which dictate the standard behavior of Support. These rules may
sometimes make it seem like placeholders in ticket triggers failed to work,
but this isn’t a mistake. These rules protect you because they prevent
spammers from using your account to distribute spam messages. See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408833443226" target="_blank">Understanding placeholder suppression
rules</a>.</p>
<div class="p">This article includes these sections:<ul class="ul" id="topic-1__ul_tpq_2zb_4fb">
<li class="li"><a class="xref" href="#topic_qyc_zyb_4fb">Using placeholders
in business rules</a></li>
<li class="li"><a class="xref" href="#topic_nfp_nja_vb">Using placeholders
for custom fields</a></li>
<li class="li"><a class="xref" href="#topic_nfn_yxq_j2b">Using placeholders
for checkbox custom fields</a></li>
</ul>
</div>
<p class="p">Related articles:</p>
<ul class="ul" id="topic-1__ul_dtm_4l4_wmb">
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408886858138-Zendesk-placeholders-reference" target="_blank">Zendesk Support placeholders
reference</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408833443226" target="_blank">Understanding placeholder
suppression rules</a></li>
</ul>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_qyc_zyb_4fb">
<h2 class="title topictitle2" id="ariaid-title2">Using placeholders in business rules</h2>
<div class="body">
<p class="p">Placeholders can be used in some, but not all, business rule actions.
When placeholders are supported, a <strong class="ph b">View available
placeholders</strong> button is visible beneath the field.
Placeholders are formatted within matched double curly brackets.
Usually they are used in notification messages and reference ticket
properties. If a placeholder references a field that doesn't have a
value, the placeholder is blank in the automation, trigger, or
macro. </p>
<p class="p">Here’s an example of how placeholders are used in an email
notification:</p>
<p class="p"><img class="image img-screenshot" height="NaN" id="topic_qyc_zyb_4fb__image_kln_yvv_xb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/placeholders.png" width="NaN"></p>
<p class="p">For the complete list of placeholders, and where they can be used, see
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408886858138-Zendesk-placeholders-reference" target="_blank">Zendesk Support placeholders
reference</a>. If you want more control on how
placeholder data is selected and displayed, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408883291290-Understanding-Liquid-markup-and-Zendesk-Support" target="_blank">Understanding Liquid
markup</a>.</p>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested2" id="topic_dyf_vmw_hzb">
<h3 class="title topictitle3" id="ariaid-title3">Using placeholders in macros</h3>
<div class="body">
<p class="p">When you apply a macro containing a placeholder to a ticket, the
placeholder is evaluated according to what is currently true
about the ticket. If the output of the evaluation returns
any information, it is added as a ticket comment. For
example, if a macro that returns the ticket ID is run on a
ticket that has not been saved (and therefore has no ticket
number yet), the ticket comments aren't updated. The macro
is not re-evaluated when the ticket is saved. You could
manually add the placeholder to the ticket using the
placeholder {{ticket.id}}. This would allow it to be
evaluated when you submit the ticket, and the value returned
by the placeholder would be added to the ticket
comments.</p>
<p class="p">When using macros with <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408835103898" target="_blank">problem and incident
tickets</a>, you often need use a backward slash
(\) to escape the placeholder so that it populates the
appropriate value within the related incident tickets. For
example: <code class="ph codeph">Hello
\{{ticket.requester.first_name}}</code></p>
<p class="p">When using URL-based placeholders in macros –
<code class="ph codeph">ticket.link</code> or
<code class="ph codeph">ticket.url</code> – the placeholders
insert the agent's ticket URL (for example,
subdomain.zendesk.com/agent/tickets/123).</p>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_nfp_nja_vb">
<h2 class="title topictitle2" id="ariaid-title4">Using placeholders for custom fields</h2>
<div class="body">
<p class="p">Placeholders are generated automatically, based on the ticket, current user, and custom object
properties. These are referred to as system placeholders. </p>
<p class="p">When you add custom fields for tickets, users, organizations, and custom objects, they are also
available as placeholders. You can use placeholders for your custom
fields as you would any other system placeholder. Every custom field
has a unique ID or key. When you create a custom ticket field, the
ID is automatically generated for you. When you create a custom
user, custom org, or custom object field, you enter a unique key
that cannot be edited once it is set. </p>
<p class="p">Custom fields are not included in the list of available placeholders, but all custom fields <a class="xref" href="#topic_wcz_x5s_rbc">except
drop-downs</a> follow this simple naming pattern that
references their unique ID or key.</p>
<div class="p">
<div class="tablenoborder">
<table border="1" cellpadding="4" cellspacing="0" class="table" frame="border" id="topic_nfp_nja_vb__table_1c2_xmq_5k" rules="all" summary="">
<colgroup>
<col style="width:50%">
<col style="width:50%">
</colgroup>
<tbody class="tbody">
<tr class="row">
<td class="entry nocellnorowborder" style="vertical-align:top;">Ticket custom fields</td>
<td class="entry cell-norowborder" style="vertical-align:top;">{{ticket.ticket_field_<em class="ph i">&lt;field ID number&gt;</em>}}</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" style="vertical-align:top;">User custom fields</td>
<td class="entry cell-norowborder" style="vertical-align:top;">{{ticket.requester.custom_fields.<em class="ph i">&lt;field_key&gt;</em>}}</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" style="vertical-align:top;">Organization custom fields</td>
<td class="entry cell-norowborder" style="vertical-align:top;">{{ticket.organization.custom_fields.<em class="ph i">&lt;field_key&gt;</em>}}</td>
</tr>
<tr class="row">
<td class="entry row-nocellborder" style="vertical-align:top;">Custom object fields</td>
<td class="entry cellrowborder" style="vertical-align:top;">{{custom_objects.<em class="ph i">&lt;object_key&gt;</em>.custom_fields.<em class="ph i">&lt;field_key&gt;</em>}}</td>
</tr>
</tbody>
</table>
</div>
</div>
<p class="p">For example, a custom ticket field like this has the following placeholder:</p>
<p class="p"><img class="image img-screenshot" height="NaN" id="topic_nfp_nja_vb__image_egs_gyv_xb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/placeholder_custom_field.png" width="NaN"></p>
<div class="p">
<pre class="pre">{{ticket.ticket_field_505156}}</pre>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested2" id="topic_wcz_x5s_rbc">
<h3 class="title topictitle3" id="ariaid-title5">Using placeholders for custom drop-down fields</h3>
<div class="body">
<p class="p">The placeholder name for the options in a custom drop-down list
follows a different pattern. There's only one placeholder
for all four drop-down list options because this is a
reference to the option that was selected. The ID is for the
custom drop-down list because options do not have IDs.
Again, this is a reference to the single option that was
selected. </p>
<div class="p">
<div class="tablenoborder">
<table border="1" cellpadding="4" cellspacing="0" class="table" frame="border" id="topic_wcz_x5s_rbc__table_3s1_14q_5k" rules="all" summary="">
<colgroup>
<col style="width:50%">
<col style="width:50%">
</colgroup>
<tbody class="tbody">
<tr class="row">
<td class="entry nocellnorowborder" style="vertical-align:top;">Ticket custom drop-down fields<p class="p">Ticket
custom multi-select fields</p>
</td>
<td class="entry cell-norowborder" style="vertical-align:top;">
<ul class="ul" id="topic_wcz_x5s_rbc__ul_ctp_ztz_rbc">
<li class="li">To display the value of the selected option,
use:<p class="p">{{ticket.ticket_field_option_title_<em class="ph i">&lt;field
ID number&gt;</em>}}</p>
</li>
<li class="li">To display the tags associated with the
selected option,
use:<p class="p">{{ticket.ticket_field_<em class="ph i">&lt;field ID
number&gt;</em>}}</p>
<p class="p"></p>
</li>
</ul>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" style="vertical-align:top;">User custom drop-down fields</td>
<td class="entry cell-norowborder" style="vertical-align:top;">{{ticket.requester.custom_fields.<em class="ph i">&lt;field_key&gt;</em>.title}}</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" style="vertical-align:top;">Organization custom drop-down
fields</td>
<td class="entry cell-norowborder" style="vertical-align:top;">{{ticket.organization.custom_fields.<em class="ph i">&lt;field_key&gt;</em>.title}}</td>
</tr>
<tr class="row">
<td class="entry row-nocellborder" style="vertical-align:top;">Custom object drop-down fields</td>
<td class="entry cellrowborder" style="vertical-align:top;">{{custom_objects.<em class="ph i">&lt;object_key&gt;</em>.custom_fields.<em class="ph i">&lt;field_key&gt;</em>.title}}</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="note">
<span class="notetitle">Note:</span> Take note of the syntax, as the placement of <em class="ph i">title</em> in
the placeholder varies, depending on the type of custom
field.</div>
<p class="p">For example, the placeholder for a drop-down list for a custom
ticket field would look like this:</p>
<p class="p"><code class="ph codeph">{{ticket.ticket_field_option_title_515416}}</code></p>
<p class="p">To locate the custom field ID or key, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/9199731160474" target="_blank">Finding the field key
or field ID for a custom field</a>.</p>
</div>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested2" id="topic_n4g_3vs_rbc">
<h3 class="title topictitle3" id="ariaid-title6">Using placeholders for custom lookup fields</h3>
<div class="body">
<p class="p">Lookup relationship fields are a type of custom field that is
used to define relationships between objects. They are
supported for all of the standard Zendesk objects (tickets,
users, and organizations) and custom objects.</p>
<p class="p">In addition to using placeholders to surface data related to the
primary object, such as a ticket requester's name, you can
also use placeholders to surface data in related records.
For example, if you have a ticket with a lookup relationship
field that points to a user, you could use placeholders to
reference data about that user. Similarly, you could use a
placeholder to reference ticket data through a custom
object's lookup relationship field and vice versa. For the
purposes of these placeholders, the standard ticket
<em class="ph i">requester</em> and <em class="ph i">organization</em> fields are
treated as lookup relationship fields. </p>
<p class="p">To reference data in related records, use the lookup relationship
field's field key. This will follow the pattern for custom
fields. See <a class="xref" href="#topic_b4k_1zn_zbc">examples</a>.</p>
<p class="p">You can also use placeholders supported for the target object in
a lookup relationship field. For example, a lookup
relationship field that points to users can leverage the
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408886858138#topic_qdz_opl_rc" target="_blank">user data
placeholders</a>.</p>
<p class="p">Placeholders referencing data through a ticket lookup
relationship field can be used in ticket triggers and
macros. Placeholders referencing data through custom object
lookup relationship fields can be used in object triggers. </p>
</div>
<div aria-labelledby="ariaid-title7" class="topic nested3" id="topic_b4k_1zn_zbc">
<h4 class="title topictitle4" id="ariaid-title7">Examples of using placeholders to retrieve data from related records</h4>
<div class="body">
<p class="p"><strong class="ph b">Working with the ticket <em class="ph i">Requester</em> field</strong></p>
<p class="p">For example, the <em class="ph i">Requester</em> field in a ticket is
functionally a lookup relationship field pointing to
a user. If you've defined a user lookup relationship
field with a field key of <em class="ph i">manager</em> that points
to another user, then you could use the following
placeholder to display the asset requester's
manager's name:</p>
<p class="p"><code class="ph codeph">ticket.requester.custom_fields.manager</code></p>
<p class="p">You could also take it one step further because you're
working with the ticket requester field, and create
a side conversation email to the ticket requester's
manager using the following placeholder:</p>
<p class="p"><code class="ph codeph">ticket.requester.custom_fields.manager.email</code></p>
<p class="p">This is great for approval workflows, where you might
need to notify the manager or get the manager's
sign-off.</p>
<p class="p"><strong class="ph b">Working with custom organization lookup relationship
fields</strong></p>
<p class="p">The <em class="ph i">Organization</em> field is another standard ticket
field that is functionally a lookup relationship
field pointing to an organization. You could use
organization lookup relationship fields to associate
an organization with a custom object named
<em class="ph i">contract</em>. Then you could leverage the
ticket's <em class="ph i">organization</em> field to retrieve data
from the contract record associated with the
organization, which itself (the organization) is
associated with the ticket, and use the following
placeholder to communicate the contract's end
date:</p>
<p class="p"><code class="ph codeph">{{ticket.organization.custom_fields.contract.custom_fields.end_date}}</code></p>
<p class="p">Both the <em class="ph i">requester</em> and <em class="ph i">organization</em> ticket
fields are special cases because they are standard
ticket fields that function as lookup relationship
fields. Therefore, you can go two "hops" deep with
the lookup relationship field placeholders to
retrieve data from a record related to the record
related to the primary object. In the example above,
the ticket is the primary object, the ticket's
organization is the first "hop", and the contract
record related to the organization is the second
"hop." </p>
<p class="p">When dealing with custom lookup relationship fields, you
can go only one "hop" deep into the record directly
related to the primary object.</p>
<p class="p"><strong class="ph b">Working with custom lookup relationship fields</strong></p>
<p class="p">An example of working with custom lookup relationship
fields might be a ticket lookup relationship field
with a field key of <em class="ph i">2698798899085</em> that points
to a custom object named <em class="ph i">Order</em>. The order
object has a custom drop-down field with the field
key <em class="ph i">order_status</em>. To reference the status of
the order record that's associated with the ticket,
use the following placeholder:</p>
<p class="p"><code class="ph codeph">{{ticket.ticket_field_2698798899085.custom_fields.order_status.title}}</code></p>
<p class="p">When working with drop-down fields, you must include
<code class="ph codeph">.title</code> in the placeholder to
return the selected value.</p>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title8" class="topic nested2" id="topic_dj4_3wz_hkc">
<h3 class="title topictitle3" id="ariaid-title8">Using placeholders for multi-lookup fields</h3>
<div class="body">
<p class="p">When using placeholders to retrieve data for multi-lookup fields,
using
<code class="ph codeph">{{ticket.ticket_field_<em class="ph i">&lt;field_id&gt;</em>}}</code>
to reference a multi-lookup field returns a comma-separated
list of target record names.</p>
<div class="p">You can use placeholders in combination with <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408883291290-Understanding-Liquid-markup-and-Zendesk-Support" target="_blank">Liquid markup</a>
to loop over a placeholder reference to a multi-lookup field
to retrieve data from the target records. For example, the
following would result in a list of the related record's
name and ID
values:<pre class="pre codeblock" id="topic_dj4_3wz_hkc__codeblock_o25_zwz_hkc"><code>{% for t in ticket.ticket_field_&lt;field_id&gt; %}
{{ t.name }}: {{ t.id }}
{% endfor %}</code></pre>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title9" class="topic nested2" id="topic_nfn_yxq_j2b">
<h3 class="title topictitle3" id="ariaid-title9">Using placeholders for custom checkbox fields</h3>
<div class="body">
<p class="p">You can use placeholders in combination with <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408883291290-Understanding-Liquid-markup-and-Zendesk-Support" target="_blank">Liquid markup</a>
to verify if a checkbox (custom field) has been selected on
a ticket and provide customized output based on the checkbox
status (selected or not selected). </p>
<p class="p">When you use Liquid markup <code class="ph codeph">if/else/case</code>
statements for checkbox custom ticket fields, remember that
the checkbox field has a value of <strong class="ph b">0</strong> or <strong class="ph b">1</strong>, not
<strong class="ph b">false</strong> or <strong class="ph b">true</strong>. For example:</p>
<pre class="pre codeblock"><code>{% if ticket.ticket_field_&lt;insert field_id here&gt; contains 1 %}
checkbox is checked
{% else %}
checkbox is unchecked (or null)
{% endif %}</code></pre>
</div>
</div>
</div>
<script id="docs-schema-markup" type="application/ld+json">{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408887218330-Using-placeholders",
"url": "https://support.zendesk.com/hc/en-us/articles/4408887218330-Using-placeholders",
"headline": "Using placeholders",
"description": "You can use placeholders to reference ticket, user, and custom data in email notifications and business rules, with specific syntax for different field types and lookup relationships to customize automated messages.",
"articleSection": "Business rules",
"datePublished": "2021-10-16T16:28:56+00:00",
"dateModified": "2026-08-25T17:57:40.899006+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408887218330-Using-placeholders"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"url": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"url": "https://support.zendesk.com/hc/en-us"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk"
}
}</script><script id="ai-summary-script">
//<![CDATA[
const ai_summary_style = document.createElement('style');
ai_summary_style.innerHTML = `#styled-article-body{padding:0 0 0}#article-body #docs-ai-summary{background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 6px;margin-bottom:16px}#article-body #docs-ai-summary #docs-ai-summary-toggle{font-size:.9em;font-weight:700;margin-bottom:4px;cursor:pointer;display:flex;justify-content:space-between;align-items:center}#article-body #docs-ai-summary #docs-ai-summary-toggle #up-triangle{margin-left:auto;padding-right:10px;display:none}#article-body #docs-ai-summary #docs-ai-summary-toggle #down-triangle{margin-left:auto;padding-right:10px}#article-body #docs-ai-summary #docs-ai-summary-content{font-size:.9em;padding-left:25px;padding-right:25px;margin-bottom:12px}`;
document.head.appendChild(ai_summary_style);

const toggleAISummary = () => {
const summary = document.getElementById("docs-ai-summary-content");
const upTriangle = document.getElementById("up-triangle");
const downTriangle = document.getElementById("down-triangle");
if (summary.style.display === "none") {
summary.style.display = "block";
upTriangle.style.display = "none";
downTriangle.style.display = "inline";
} else {
summary.style.display = "none";
upTriangle.style.display = "inline";
downTriangle.style.display = "none";
}
};

document.getElementById("docs-ai-summary-toggle").addEventListener("click", toggleAISummary);
//]]>
</script>
</body>