DocuGen placeholders are the text strings that represent HubSpot properties inside your document. For example, if you want to insert a Deal's name inside a document, you should use {{ deal.dealname }}. When you generate a document or send one for signature, DocuGen automatically populates this placeholder with the actual Deal name. 

Our Live editor allows you to insert placeholders into your template without worrying about how to write them. But if you need to take matters into your own hands, the rest of this article describes the syntax (structure) of the DocuGen placeholders.

DocuGen placeholders can be used for populating templates and for custom email subjects and bodies.

Delimiters

All DocuGen placeholders start with {{ and end with }}. For example: {{ deal.dealname }}.

There are a few exceptions to this rule: repeat, condition, and signature use {% %}. More below.

Start object

Each DocuGen recipe you create is based on a specific HubSpot object the documents are made from. For example, a recipe can be for Deals or Companies or Contacts. These are the start objects for the recipe.

The start object's internal HubSpot name is the first part of the DocuGen placeholder. For example:

• "deal" is the internal HubSpot name for the Deal object. {{ deal.dealname }} is a placeholder that will fetch values from the Deal object and must only be used in DocuGen recipes for deals.
• "contact" is the internal HubSpot name for the Contact object. {{ contact.firstname }} will insert values from the Contact object and must only be used in DocuGen recipes for Contacts.

Property name

The last part of the placeholder is the HubSpot property internal name (not its label). For example:

• The internal name for Deal Name is dealname. To insert the Deal Name into a document, we use {{ deal.dealname }}. 
• The internal name for the Deal Amount is amount. {{ deal.amount }} will insert the Deal Amount into the document.

Crossing objects

DocuGen placeholders allow you to access records that are associated with the start object, such as the owner of a company or the line items of a deal. 

You can cross objects in DocuGen placeholders by adding the associated object names between the start object and the desired property. For example, if the start object is Deal, we can access the following: 

• Properties that belong to the owner of the deal. For example, {{ deal.owner.firstName }} will be populated with the first name of the deal owner (HubSpot user). In this example, we crossed one object, the owner.
• Properties that belong to the manager of the owner of the deal. For example, {{ deal.owner.manager.hs_given_name }} will be populated with the first name of the deal owner's manager. In this example, we crossed two objects: the owner and the owner's manager.
• Multiple records that are associated with the deal. For example, line items, contacts, or companies. More on this below.

Crossing to a single associated record

{{ deal.owner.firstName }} and {{ deal.owner.manager.hs_given_name }} are examples of placeholders that cross to a single record, respectively the owner and the owner's manager. This is because a deal has one owner, and the owner has one manager. That's why the placeholder uses singular for 'owner', 'manager', etc.

A note about the owner and manager (of a deal, company, contact, etc.): the owner has only 6 fields (id, email, firstName, lastName, fullName, userId); the manager takes any HubSpot User property by its internal name.

Crossing to multiple associated records

Each deal can have multiple Line items, Attachments, Tickets, or other linked records. When crossing those objects, DocuGen will fetch the associated records and insert them as a list or a table. 

See the next section, Multiple associated records, to learn more.

Multiple associated records

Your recipe's start object can be associated with multiple records:

• A deal can have multiple contacts and companies
• A company can have multiple contacts
• A contact can have multiple tickets

DocuGen allows you to insert those associated records (1) as a list, (2) as a table, or (3) as a single record based on the association label.

Insert associated records as a list

A list displays the values of associated records as a single column. For example, this is how to list the product name of the line items:

Explanation:

• {% repeat ...} {% endrepeat %} indicate that these are associated records.
• {% repeat deal.line_items %} indicates that the list should cross to the Deal's Line Items, which could be multiple records. That's why the placeholder uses the plural 'line_items'. 
• {{ name }} indicates that the list should contain the property 'name' from the Line Items.

You can format the list with bullet points or numbered lists or other formatting capabilities:

You can also insert multiple properties on each line:

Insert associated records as a table

You can display associated records as a table. Here is an example for Line Items using a Deal recipe:

This is the result after populating the table and placeholders with actual values:

Explanation:

• {% repeat ...} {% endrepeat %} indicate that these are associated records.
• {% repeat deal.line_items %} indicates that the table should cross to the Deal's Line Items. That's why the placeholder uses the plural 'line_items'. 
• {{ name }}, {{ price }}, {{ quantity }}, etc.  indicate the values to populate in each column. 

Insert single associated record based on association label

Label "Billing Contact" on a contact-to-company link -> {{ contact.billing_contact_company.name }} (lower case, spaces as _, then the object).

Formatting options

• {{ deal.closedate | date_format: "dd/MM/yyyy" }} Note: MM is the month, mm is minutes (dd/mm/yyyy prints minutes)
• {{ deal.amount | currency: "EUR" }} prints EUR5,225.00. The filter puts the text in front of the number as it is, it does not read a currency code. deal.amount already prints in the deal's currency, so you rarely need this filter.
• {{ deal.amount | currency: "€" }} prints €5,225.00. The filter puts the text in front of the number as it is, it does not read a currency code. deal.amount already prints in the deal's currency, so you rarely need this filter.{{ contact.jobtitle | default: "N/A" }} (prints "N/A" when empty)
• {{ quantity | number_format: 2 }} 

Conditions

{% if deal.amount > 10000 %}Large deal{% else %}Standard deal{% endif %}

Images and files

• Images on the record's Attachments card, {{ deal.attachments }} prints all of them. To place them one by one:

{% repeat deal.attachment_items %}{{ image }} {{ name }}{% endrepeat %}

• A property that holds an image URL: add .image to print the picture, e.g. {{ company.hs_logo_url.image }}. Without .image it prints the URL.
• A file property prints the image (a non-image file prints its file name).

Other considerations

1. A placeholder that does not exist prints nothing (no error). So a typo gives an empty spot, not a message.
2. Numbers and money print the way HubSpot shows them (currency symbol, grouping).
3. In the case of multiple associated records, you can insert the primary record details using the singular object name. For example, {{ contact.company.name }} will insert the name of the primary company associated with the contact. If no company is labeled as the primary one, the placeholder will use the most recently added one.
4. A placeholder can cross at most two associations from the start object: {{ deal.company.owner.email }} works.
5. The Live editor's placeholder picker shows every valid path for the portal. Copying from it is the safest way.

6. A property just created in HubSpot is not known yet: click "Reload schema" in the editor:

7. Word sometimes splits a placeholder into pieces when you edit its style. DocuGen handles that, so this is not a cause of an empty value.