DOCX Template Variables

DocuTrust supports variable substitution in DOCX templates. Use [[variable_name]] syntax to insert dynamic content, and [[if:variable]]...[[end]] for conditional blocks that appear only when a variable has a value.

Variable syntax

Basic variables

Wrap variable names in double square brackets:

[[variable_name]]

When the document is processed, each [[variable_name]] placeholder is replaced with the corresponding field value from the signer’s submission. Example DOCX content:

Dear [[signer_name]],

This agreement is entered into on [[signing_date]] between [[company_name]]
("Company") and [[signer_name]] ("Contractor").

The Contractor agrees to provide services at a rate of $[[hourly_rate]] per hour,
not to exceed [[max_hours]] hours per month.

Contractor Email: [[signer_email]]
Contractor Phone: [[phone_number]]
Start Date: [[start_date]]
End Date: [[end_date]]

Variable naming rules

Rule	Valid	Invalid
Use lowercase letters, numbers, and underscores	`signer_name`, `rate_2026`	`Signer Name`, `rate-2026`
Must start with a letter	`full_name`	`2nd_signer`
No spaces	`company_name`	`company name`
No special characters (except underscore)	`address_line_1`	`address.line.1`

Conditional blocks

Use [[if:variable]]...[[end]] to create sections that only appear when the referenced variable has a non-empty value.

[[if:addendum_text]]
ADDENDUM

The following additional terms apply to this agreement:

[[addendum_text]]

Both parties acknowledge and agree to the terms of this addendum.

Signer: [[signer_name]]
Date: [[signing_date]]
[[end]]

If addendum_text is empty or not provided, the entire block (from [[if:addendum_text]] to [[end]]) is removed from the final document.

Nested conditionals

Conditional blocks can be nested:

[[if:has_insurance]]
INSURANCE REQUIREMENTS

The Contractor shall maintain the following insurance coverage:
- General liability: $[[liability_amount]]

[[if:has_workers_comp]]
- Workers' compensation: As required by law in [[state]]
[[end]]

[[if:has_professional_liability]]
- Professional liability: $[[professional_liability_amount]]
[[end]]

Proof of insurance must be provided within [[insurance_deadline_days]] days of signing.
[[end]]

Built-in variables

DocuTrust provides several built-in variables that are automatically available in every DOCX template. You do not need to define fields for these — they are populated from the submission context.

Variable	Description	Example value
`signer_name`	The current signer’s full name.	`Jane Smith`
`signer_email`	The current signer’s email address.	`jane@example.com`
`signing_date`	The current date when the signer opens the form (formatted per account locale).	`April 9, 2026`
`submission_id`	The unique submission identifier.	`187`
`template_name`	The name of the template.	`Service Agreement`
`account_name`	Your account/company name from settings.	`Acme Inc`

Example using built-in variables:

SERVICE AGREEMENT

Template: [[template_name]]
Reference: SUB-[[submission_id]]

This agreement is entered into on [[signing_date]] by:

Name: [[signer_name]]
Email: [[signer_email]]
Company: [[account_name]]

Mapping fields to variables

DOCX variables are mapped to template fields by the field’s key property. When you create a template from a DOCX file, DocuTrust auto-detects [[variable_name]] placeholders and creates corresponding fields in the schema.

Automatic field creation

When uploading a DOCX with variables:

curl -X POST "$DOCUTRUST_URL/api/templates/docx" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN" \
  -F "file=@/path/to/contract.docx" \
  -F "name=Service Agreement"

DocuTrust scans the document for [[variable]] placeholders and creates text fields for each one. The resulting template schema:

{
  "id": 42,
  "name": "Service Agreement",
  "slug": "qk7x9m2p",
  "external_id": null,
  "folder_name": "Default",
  "source": "api",
  "shared": false,
  "field_count": 6,
  "submitter_count": 1,
  "schema": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Company Name",
      "type": "text",
      "submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "required": true,
      "readonly": false,
      "key": "company_name",
      "default_value": null,
      "placeholder": null,
      "options": null,
      "areas": []
    },
    {
      "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Hourly Rate",
      "type": "text",
      "submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "required": true,
      "readonly": false,
      "key": "hourly_rate",
      "default_value": null,
      "placeholder": null,
      "options": null,
      "areas": []
    },
    {
      "uuid": "d4e5f6a7-b8c9-0123-def0-234567890123",
      "name": "Max Hours",
      "type": "text",
      "submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "required": true,
      "readonly": false,
      "key": "max_hours",
      "default_value": null,
      "placeholder": null,
      "options": null,
      "areas": []
    },
    {
      "uuid": "e5f6a7b8-c9d0-1234-ef01-456789012345",
      "name": "Phone Number",
      "type": "text",
      "submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "required": false,
      "readonly": false,
      "key": "phone_number",
      "default_value": null,
      "placeholder": null,
      "options": null,
      "areas": []
    },
    {
      "uuid": "f6a7b8c9-d0e1-2345-f012-567890123456",
      "name": "Start Date",
      "type": "text",
      "submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "required": true,
      "readonly": false,
      "key": "start_date",
      "default_value": null,
      "placeholder": null,
      "options": null,
      "areas": []
    },
    {
      "uuid": "a7b8c9d0-e1f2-3456-0123-678901234567",
      "name": "End Date",
      "type": "text",
      "submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "required": true,
      "readonly": false,
      "key": "end_date",
      "default_value": null,
      "placeholder": null,
      "options": null,
      "areas": []
    }
  ],
  "submitters": [
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "First Party"
    }
  ],
  "thumbnail_url": null,
  "created_at": "2026-04-09T10:00:00.000Z",
  "updated_at": "2026-04-09T10:00:00.000Z"
}

Built-in variables (signer_name, signer_email, signing_date, submission_id, template_name) are not created as fields since they are populated automatically from the submission context.

Pre-filling variables via submission

When creating a submission, pre-fill DOCX variables using the values object keyed by the field’s key property:

curl -X POST "$DOCUTRUST_URL/api/submissions" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 42,
    "send_email": true,
    "submitters_order": "sequential",
    "expire_at": "2026-05-08T00:00:00.000Z",
    "metadata": {
      "deal_id": "DEAL-2026-0042",
      "department": "Sales"
    },
    "submitters": [
      {
        "role": "First Party",
        "email": "jane@example.com",
        "name": "Jane Smith",
        "phone": "+15551234567",
        "external_id": "cust-001",
        "metadata": {},
        "values": {
          "company_name": "Acme Corp",
          "hourly_rate": "75",
          "max_hours": "160",
          "phone_number": "+15551234567",
          "start_date": "2026-05-01",
          "end_date": "2026-12-31"
        },
        "preferences": {
          "send_email": true,
          "sign_mode": "normal"
        }
      }
    ]
  }'

Formatting in DOCX

DOCX variables preserve the formatting of the surrounding text. If [[company_name]] is bold in the DOCX file, the substituted value will also be bold. Formatting rules:

Scenario	Result
Variable placeholder is bold	Substituted value is bold
Variable placeholder is italic	Substituted value is italic
Variable placeholder has a specific font size	Substituted value uses that font size
Variable spans multiple font styles	The first style is applied to the entire value

Avoid splitting a variable placeholder across multiple runs in the DOCX XML. Word sometimes inserts formatting markers mid-word (e.g., [[company_ in one run and name]] in another). If variable substitution is not working, try retyping the entire [[variable_name]] placeholder in a single action.

To debug variable detection issues, download the template’s documents via the API and check the schema response. All detected variables appear as fields with matching key values.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

DOCX Template Variables

DOCX Template Variables

Variable syntax

Basic variables

Variable naming rules

Conditional blocks

Nested conditionals

Built-in variables

Mapping fields to variables

Automatic field creation

Pre-filling variables via submission

Formatting in DOCX

​DOCX Template Variables

​Variable syntax

​Basic variables

​Variable naming rules

​Conditional blocks

​Nested conditionals

​Built-in variables

​Mapping fields to variables

​Automatic field creation

​Pre-filling variables via submission

​Formatting in DOCX

DOCX Template Variables

Variable syntax

Basic variables

Variable naming rules

Conditional blocks

Nested conditionals

Built-in variables

Mapping fields to variables

Automatic field creation

Pre-filling variables via submission

Formatting in DOCX