Document Templates

SignatureAPI can generate a document from a static DOCX template combined with dynamic data you provide. Use this to create personalized documents without editing files manually before each send.

How it works

Create a DOCX file and embed fields and conditionals using double curly braces: {{key}}. When you create an envelope, provide the data in the data property of the document. SignatureAPI merges the template with your data and produces the final document.

Provide the template URL in the url property and set format to docx.

// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "title": "Exploration Agreement",
  "documents": [
    {
      "url": "https://www.example.com/agreement-template.docx",
      "format": "docx",
      "data": {
        "person": {
          "name": "Sherlock Holmes",
          "address": "221b Baker Street, London"
        },
        "jurisdiction": "The United Kingdom",
        "mediation": false
      }
    }
  ],
  //...
}

Fields

Fields mark locations in the template where data is inserted. Use double curly braces to define a field: {{key}}.

Template:

Data:

{
  "name": "Sherlock Holmes"
}

Result:

Nested objects

Data values can be nested objects. Use dot notation in the template to reference nested keys.

Template:

Data:

{
  "person": {
    "name": "Sherlock Holmes",
    "address": {
      "houseNumber": "221b",
      "streetName": "Baker Street",
      "city": "London"
    }
  }
}

Result:

Conditionals

Conditionals control which sections appear in the final document based on your data.

If

Use {{if condition}} and {{endif}} to show or hide a block of content.

Template:

With "showDisclaimer": true, the disclaimer appears. With "showDisclaimer": false, it is omitted.

If-Else

Use {{if condition}}, {{else}}, and {{endif}} to display one of two blocks based on a condition.

Template:

With "mediation": true:

With "mediation": false:

Repeating regions

If your data contains an array, you can mark a region of the document to be repeated once per item in that array.

The simplest approach is to keep each repeating region in its own document. Most envelopes that need repeating content can be built this way without any extra template syntax. The advanced approach, range tags, is only needed when several repeating regions must live inside the same document.

How a repeating region works

A repeating region has two parts:

1. An array in the document’s data payload.
2. A region in the DOCX template, marked with field tags that reference the items of that array.

Field tags inside a repeating region use the array’s name as part of the path, for example {{events.name}}. The engine detects the binding and duplicates the region once per item in the array.

events here is just the JSON key you chose for your array. It is your name, not a reserved word. Replace it with whatever fits your data.

A dynamic table

Build a one row data table (header row plus a single data row) and place the field tags directly in the cells of the data row.

Template:

Data:

{
  "data": {
    "events": [
      { "name": "Opening Reception", "date": "Mar 12", "guests": "120" },
      { "name": "Closing Dinner",    "date": "Mar 14", "guests": "80"  }
    ]
  }
}

Result:

The header row sits above the data row and is not repeated. The engine duplicates the data row once per item in the array.

This works because the array events is referenced only inside the data row of one table. As soon as you reference the same array somewhere else in the document, the simple pattern breaks. To repeat content in more than one place, see the next sections.

A repeating paragraph or bullet

The same idea applies to a single paragraph or a single bullet (or numbered) list item. Place the field tags in the line you want to repeat. Do not wrap anything.

Template:

Data:

{
  "data": {
    "events": [
      { "name": "Opening Reception", "date": "Mar 12" },
      { "name": "Closing Dinner",    "date": "Mar 14" }
    ]
  }
}

Result:

The line containing the field tags is what gets duplicated. The lines before and after appear once.

For a bullet item, write a single bullet with the field tags inside, and the engine produces one continuous list with one entry per item.

Nested values inside a region

Items in the array can be objects with nested fields. Use dot notation to reach them.

Template:

Data:

{
  "data": {
    "events": [
      { "name": "Opening Reception", "venue": { "hall": "Main Hall",   "city": "London" } },
      { "name": "Closing Dinner",    "venue": { "hall": "Garden Tent", "city": "London" } }
    ]
  }
}

Result:

The same dot notation works inside paragraphs and bullets.

Combining several repeating regions

When an envelope needs more than one repeating region, the recommended approach is to split the content across multiple documents in the same envelope. Each document has its own template and its own data payload, and each document can stay simple.

{
  "documents": [
    {
      "url": "https://www.example.com/schedule.docx",
      "format": "docx",
      "data": { "events": [ ... ] }
    },
    {
      "url": "https://www.example.com/signatories.docx",
      "format": "docx",
      "data": { "signatories": [ ... ] }
    }
  ]
}

The recipient sees a single envelope. Internally, each document is processed with its own template and its own data. This avoids the extra template syntax described in the next section.

Several repeating regions in one document

If you really need more than one repeating region inside the same document, the simple pattern shown above is no longer enough. The engine has to be told where each region starts and ends, with two extra pieces of syntax:

1. A root wrapper around the entire document body.
2. A pair of range tags around each repeating region.

{{#data}}
  ...prose...
  {{#data.<arrayName>}}
    ...content to repeat...
  {{/data.<arrayName>}}
  ...more prose...
  {{#data.<otherArrayName>}}
    ...content to repeat...
  {{/data.<otherArrayName>}}
{{/data}}

Inside the root wrapper, all field paths are fully qualified: {{data.<arrayName>.<fieldName>}}. Only one root wrapper is supported per document.

The placement of the range tags differs by region type:

• Paragraphs and bullets: place the range tags on their own lines, immediately above and below the line you want to repeat. The tag lines do not appear in the output.
• Tables: place {{#data.<arrayName>}} at the start of the first cell of the data row (before its field tag) and {{/data.<arrayName>}} at the end of the last cell of the same data row (after its field tag). The header row is not repeated; only the data row is.

A combined example

This template uses all three region types in one document.

Template:

Data:

{
  "data": {
    "events": [
      { "name": "Kickoff",  "date": "Mar 12", "guests": "120" },
      { "name": "Workshop", "date": "Mar 13", "guests": "40"  },
      { "name": "Closing",  "date": "Mar 14", "guests": "200" }
    ],
    "signatories": [
      { "name": "Sherlock Holmes", "title": "Director" },
      { "name": "John Watson",     "title": "Co-Director" }
    ],
    "notes": [
      { "text": "Bring ID." },
      { "text": "Dress code is formal." }
    ]
  }
}

Result:

Each region iterates independently. The headings and surrounding text appear once.

Why the wrapper is required

Without the root wrapper and the range tags, the engine has to guess where each region starts and ends. With more than one array, or more than one binding to the same array, the guesses fail in characteristic ways: text gets dragged between regions, or the regions multiply against each other (three by three by three produces 27 copies of the innermost block, not 3). The DSWord engine docs note this directly: “When range tags are omitted, the template automatically calculates the start and end of a repeating block and may produce unwanted results.”

The wrapper plus range tags remove the guesswork.

Pitfalls

• Prefer multiple documents over range tags. Only reach for the root wrapper and range tags when a single document genuinely needs more than one repeating region.
• Pick one approach per template. The simple pattern (no wrappers) and the range tag pattern (root wrapper plus range tags around each region) cannot be mixed in the same document.
• The simple pattern only works when the array is referenced once in the document. As soon as you have a second binding to the same array, or a second array used elsewhere in the document, switch to range tags.
• Range tags around a table belong inside the cells of the data row, not in paragraphs around the table. Otherwise the entire table is duplicated, header and all.
• Do not write literal {{...}} in non repeating prose, even as documentation or examples. The engine attempts to evaluate it and fails with a template-error. To refer to a field name in body text, write it without the braces (for example, “the events.name field”).
• Every item in the array must include every field referenced inside the region. A missing field produces a cannot-populate-template error.
• Field names are case sensitive. {{events.Name}} and {{events.name}} are different paths.
• Place placeholders ([[place_key]]) do not belong inside a repeating region. The region is duplicated and each copy would compete for the same place. Position signatures and other places outside the repeating region.