Use dynamic content variables in DOCX to create personalized documents

1. Dynamic content variables

Dynamic content variables are a powerful feature for building personalized documents for each signer. They enable automatic insertion of data such as the signer's name, email address, signing date, and other details. During template generation, these values are directly populated into the DOCX template, as if each document had been created manually.

1.1 Simple variables

Simple variables use the format [[variable_name]] and can be applied to insert text, numbers, or dates. For example, if you add the variable [[signer_name]] into a DOCX file, it will be replaced with the signer's actual name when the template is generated.

Example:

The Purchase Agreement is between [[signer_name]] and Urbanpay.

1.2 Conditional logic

Conditional logic variables allow you to include or exclude specific parts of the document. They are especially useful for creating templates with multiple content variations depending on certain conditions.

The [[if:var]]...[[end]] condition allows you to include or exclude a block of text based on the logical value true/false of a variable. If the variable is not set or has the value false, the block of text will be skipped.

The [[if:var]]...[[else]]...[[end]] condition allows you to include one of two text blocks based on the boolean value true/false of a variable. If the variable is set to true, the first block of text is included; otherwise, the second [[else]] block is used.
Note: The variable_name in [[end:variable_name]] is optional, but including it can improve readability.

Example:

Your order has been processed.
[[if:is_vip]] Thank you for being a valued VIP customer! [[end]]

---

Your order has been processed.
[[if:is_vip]]
Thank you for being a valued VIP customer!
[[else]]
Thank you for being our customer.
[[end:is_vip]]

1.3 Lists and tables

[[for:items]]...[[end]] loops allow you to generate repeated blocks of content based on array variables. This is especially useful for generating lists or rows where the number of items may vary. Array variables can be provided in two formats: as an array of simple values (e.g., strings or numbers) or as an array of objects (where each object contains multiple properties).

The array of objects allows you to create a list or table based on an array of objects, where each object contains multiple properties. You can access each property of the object using dot notation within the loop and the singular form of the items list variable (e.g., invoices → invoice).

Here is an example of a DOCX table generated with a for loop and array variables:

Example:

[[for:items]]

-[[item.name]] ([[item.quantity]])
[[end]]

JSON

{
  "invoices": [
    { "name": "Dell XPS 15 Laptop", "quantity": "2", "price": "1250.00", "total": "2500.00" },
    { "name": "Logitech MX Master 3S Mouse", "quantity": "1", "price": "150.00", "total": "150.00" }
  ]
}

2. Embedded field text tags

While content variables allow you to insert dynamic content anywhere in a DOCX file, embedded field text tags are used to insert special fields such as signature blocks, dates, initials, and other interactive elements. These tags are recognized by the system when the template is generated and are replaced with the corresponding interactive fields. Each tag includes a defined field name along with its associated attributes:

name: Name of the field in the template.

type: Field type can be one of the following types: text, signature, initials, date, datenow, image, file, payment, stamp, select, checkbox, multiple, radio, phone, verification, kba.

role: signer role name. Specify different names in case the document contains multiple signing parties with their own set of fields.

default: default field value to be used in the template (optional).

required: set false to make the field optional and skippable. true by default.

readonly: set true to make it impossible for the signer to edit the pre-filled field value. false by default.

title: field title shown instead of the field name in the signing interface.

description: the field description displayed after the field name or title in the signing interface.

options: comma separated list of options for select and radio field types.

condition: FieldName:value to show the field only if the condition is met for the value in other field. Pass only FieldName to set a condition for a non-empty field.

width: absolute width of the field in pixels. This attribute is optional, text tag width will be used for the field width by default.

height: absolute height of the field in pixels. This attribute is optional, font size height will be used for the field height by default.

format: the data format for date and signature fields. Possible values depend on the field type:

• date field can be, for example: DD/MM/YYYY (Default: MM/DD/YYYY)
• signature field can accept only: drawn, typed, drawn_or_typed, upload. (Default: drawn_or_typed)
• number field can accept: usd, eur, gbp currency formats.

3. Send DOCX to the API

Use POST API to create a one-off submission request document from the given DOCX with content variables and embedded text field tags.

API request body should contain JSON payload with "file": '...' encoded as base64 string value.