Templates & fields

Use descriptive, stable names. Inspect a template before building its replacement payload: inspection returns discovered occurrences, names, kinds, locations, parent groups, and whether the processor supports them. The same field can occur more than once.

Word templates

DOCX supports named tags, aliases, content controls, and repeating sections, including headers and footers. Put named fields inside a repeating section’s row.

Supported features include text, checkboxes, formatting, PNG/JPEG images, allowlisted HTML, DOCX composition, and explicit control removal. Validate nested sections and your own styles against real output.

Excel templates

XLSX accepts workbook-scoped or sheet-scoped defined names and direct references such as Sheet1!A1.

For repeating data, define a Section_Items range and Items_-prefixed single-cell member names. Supply a RepeatingSection field with rows containing those member names. Multi-row templates copy formulas and styles, and subsequent rows shift. Empty rows delete the prototype rows. Overlapping sections and nested Excel repeats are not supported.

Dates use UTC. Recalculation flags ask Excel to calculate when opening the workbook; they are not a complete server-side calculation engine.

PDF templates

Use fillable PDF AcroForm text fields, including qualified names. Non-text and read-only fields may be discoverable but are not writable.

DocLab does not implement arbitrary PDF text replacement, XFA forms, flattening, signing, or non-text form filling. The processor updates field values and requests viewer-generated appearances. Viewers that ignore that request may display stale appearances; test the PDF viewers used by your audience.

Typed replacement values

Only use a field kind supported by the selected processor. The API does not coerce text into numbers, so identifiers such as "00123" can remain text.

Text and repeating sections

[
  { "name": "CustomerName", "kind": "Text", "text": "Cloudwell" },
  {
    "name": "LineItems",
    "kind": "RepeatingSection",
    "rows": [
      [
        { "name": "Product", "kind": "Text", "text": "Widget" },
        { "name": "Quantity", "kind": "Number", "number": 2 }
      ]
    ]
  }
]
                

This is a Word-style example. Use the names and parent groups returned by your template’s inspection. For Excel, use the actual Section_ and member names defined in the workbook.

Formatting, images, and composition

• Format supports bold, italics, underline, strikethrough, script, six-digit RGB color/highlight, and font size.
• Image entries contain contentBase64 and optional widthInches / heightInches; images fit within printable width.
• Document entries contain contentBase64, mode (FullCopy by default or AlternativeChunk), matchSource, and insertPageBreak. Insertion requires a block control. Page breaks occur between attachments, not before the first.
• AlternativeChunk requires a compatible Word client to finish import and is rejected for PDF rendering. Use FullCopy for rendered output.
• Html rejects scripts, remote images/links, arbitrary attributes, and unsafe CSS. Supply media using typed replacements.
• Remove uses removal: { "keepContent": true } to unwrap a Word control; false deletes it and its content.

Missing fields

An empty Word rows list clears the matched repeating section. Decide which fields are required in your application; inspection does not infer business requirements.

Template safety

Avoid macros, embedded objects, external resources, linked templates/workbooks, and unsafe links. Ordinary HTTP, HTTPS, mailto, and tel hyperlinks are allowed without fetching their targets. See limits and rejected content.