sig, signature, initial, text, dateinput, check, checkbox, title, company, name, email, datesigned.
One grammar. A tag names the role exactly and case-sensitively, or by position: signerN is
positional — signer1 is the first entry in your roles array — for a generator that does
not know your roster. Say a size with dimension(60x15mm) rather than padding the tag, which moves
the text around it.
Where the field lands. The field starts where the tag starts and is centred vertically on the
tag’s own text, so it straddles the line you typed on and lands in the same place whatever type
it is. Its height comes from its type; its width is the tag’s own printed width or a minimum for
its type, whichever is larger, and dimension(...) overrides both. Write the tag on the line
above a rule — a signature block is drawn with underscores, and there is nowhere on a row of
underscores to put a tag without breaking the rule you drew.
dimension(...) sets an exact size when you want
it to reach the rule. A tag on the row below a rule puts the field below it, beside whatever
caption is there — which is how a date ends up under the line instead of on it.
Directives may follow the role, in any order: optional, validate(email),
dimension(60x15mm), key(employee_id) — the data_key a prefilled value is addressed to,
stored lower-cased, so a prefilled value must use the key in lower case — and
subject(dependant_2), naming one of the subjects the template declares as the person the field
is about. A tag can name only a subject key written in lower-case a–z, 0–9 and _. Fields
addressed to a key declared any other way in the editor can still be prefilled through
values[].subject; no tag can address one.
A segment shaped like name(...) is never a label: it is a directive the parser knows, or the
whole request is refused. The first plain word or phrase becomes the field’s label — which is why
a field labelled literally “optional” cannot be expressed by a tag, and has to be placed in the
editor.
- ⚠️ A tag stops at its directives. It cannot set a comb, a per-character input shape, a
condition, a dropdown’s options or a
validate(regex)pattern — a pattern would have to survive being typed into a document. Those are set on the field in the editor afterwards. - ⚠️ The tag stays visible unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document — where it is permanent. Extraction finds white text perfectly well.
- ⚠️ A tag that cannot be placed refuses the whole request: 400
invalid_request, naming every bad tag and its page, and nothing is created. Naming a role you did not declare is the common one. Dropping the tag silently would lose a signature field; leaving it as text would print<<sig:Main Member>>on a document somebody signs. - ⚠️ The delimiter is angle brackets because your document is probably generated. Every
{-based templating engine destroys a{{ }}tag before we ever see the PDF: Mustache and Handlebars delete{{sig:Role}}silently, so the upload succeeds and tells you the document has no tags, and docxtemplater throws.<< >>is untouched by all three, so your merge fields —{employee.full_name},{#clause}…{/}— and your tags coexist with nothing to reconfigure. A{{type:Role}}tag is refused by name rather than ignored, as is Dropbox Sign’s[sig|req|signer1], so neither can be uploaded silently and printed on a document somebody signs. - ✅ Upload the Word file itself — we do the rendering. A
.docxis accepted and converted to PDF on our side, so a docxtemplater pipeline is two steps and not three: write the tags, upload. The tags survive that render, which is the whole reason they are text rather than annotations — and the render is ours now, so the document a signer sees is the one we made from your file. A PDF you produced is taken exactly as it always was; the bytes decide which of the two you sent, never the filename.
POST /api/v1/templates in the reference.