> ## Documentation Index > Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt > Use this file to discover all available pages before exploring further. # DOCX Template Variables > Use [[variable]] syntax for dynamic content and conditional blocks in DOCX templates. # 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: ```bash theme={null} 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: ```json theme={null} { "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: ```bash theme={null} 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.