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:
⚠️ A tag stops at its directives. It cannot set a per-character input shape on a box without
cells(...), 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.
A key(...) is the data_key a prefilled value is addressed to, stored lower-cased, so a prefilled
value must use the key in lower case. The key is a key of the
core vocabulary or follows the naming grammar, namespace.attribute
(see Naming fields); a tag naming any other key refuses the whole
request. A subject(...) names one of the subjects the template declares as the person the field
is about — see Subjects. A subject key matches ^[a-z0-9_]+$ — spouse, not Spouse — and a
template declaring any other key is refused, so every key a template has is one a tag can name.
The tag itself is case-insensitive: subject(Spouse) names spouse. A tickbox’s directives
declare a question — see Questions below. cells(...) and part(...) draw the
answer in printed boxes, one character each — see Several sets of boxes and
A date in printed boxes below.
A tag is on one line and ends at the first >>. A > inside it ends it early, and a tag a
word processor wraps onto the next line is two halves; either is refused as a tag that never
closes, rather than dropped.
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.
- ⚠️ 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.
Questions
A question is several tickboxes of which a signer ticks one — or, with bounds, several. Declare it on its boxes: each tickbox tag saysquestion(...), the question’s data_key, and option(...), the
option_value that box stands for. The boxes of one document that share a question key and a
subject are one question, addressed by that one key; a value sent to it names its option, and
reaches exactly that box.
A single choice — the default, exactly one box ticked:
select(...) on any one box sets how many may be ticked:
ask(...) is at most 200 characters.
*is every box the question has, and bounds the boxes cannot meet are refused.ask(...)is the question’s wording, which a signer reads above the options. It cannot contain a colon, a bracket or a>, which end a tag’s segment, its directive and the tag itself. Without it the question is named after its key (Medical aid plan), or the core’s label for a core key.- A question of one box must say its bounds —
select(1)for a tick that must be given,select(0-1)for one that may be left. Without them it is refused, because one box whose key or subject differs from its siblings’ by a typo would otherwise be a second question the signer must tick as well. - Say
select(...)andask(...)once, or alike on every box: two boxes of one question that disagree are refused, and so is a directive written twice on one tag. - The key is a choice key of the core vocabulary — whose options are
closed, so
question(person.gender)takes anoption(...)ofmale, femaleand nothing else — or a key in the naming grammar. The option is one snake_case segment, and each box of a question names a different one. - A question about somebody takes
subject(spouse)on every box, as a lone field does:question(person.gender)asked of the member and of the spouse is two questions with one key. - A box of a question takes no
key(...)(the question is the address) and nooptional(its bounds say whether it must be answered), and only a tickbox answers a question. A box is sized as a tickbox, however long its tag;dimension(...)still sets it. - The template’s naming is judged as an edit to it would be: a question at an address a lone field already has, two questions sharing a key with different options or bounds, or a second spelling of a key your organisation already uses on another template is refused, naming the tag.
Several sets of boxes
A form often rules one answer into printed boxes, one character in each, and sometimes into several sets of them: a telephone number as a dialling code and a number.cells(...) on a text
tag makes its box a row of that many cells. Text tags on one page that share a key(...) and a
subject, each with cells(...) and part(...), are one field with one value, filled from the
left in part(...) order, whichever way round they are written on the page.
person.mobile_number, drawn in 2 sets of boxes of 3 + 7 cells, part(1) first. Neither tag states a validation, so the field takes the one its label implies over all 10 cells, phone, and every cell takes a digit. A value is sent to the key once, and fills the boxes from the left.
cells(n)takes a whole number from 1 to 120, and the parts of one answer hold at most 120 cells between them.part(k)takes a whole number from 1 to 8: one answer is drawn in at most 8 sets of boxes.
cells(...)withoutpart(...)is one row of boxes:<<text:Employee:ID number:cells(13)>>.- A part needs both
cells(...)andkey(...): the key is what says which field a part is part of, since a label can be worded two ways. - The same parts on another page are another field at the same key, which a value fills too — as two tags with one key are. On one page a key has one set of parts for each person: the same answer printed twice on one page is placed in the editor.
- The field takes the label of
part(1), or of the first part that has one, and the other parts’ labels are not kept. - A box is as wide as its tag or its type’s minimum, which is seldom the width of the boxes printed
under it, so give each part a
dimension(...)that matches them. - The rules are the editor’s Join as one answer: one role and one person, required if any part
is, and a validation the joined cells can hold. With no
validate(...)on any part, the field takes the validation its label implies, when the joined cells can hold it — a label naming a telephone number makes it a phone number, and every cell a digit. A singlecells(...)tag infers nothing from its label. In the editor, Split into separate fields undoes a join, as it undoes any Join.
A date in printed boxes
A form often prints a date as boxes too:D D M M Y Y Y Y, or day, month and year as three sets.
cells(...) on a dateinput tag makes it a date in printed boxes, and part(...) splits it across
several sets, exactly as on a text box. The field is still a date: the signer is offered a calendar,
and the digits of the day they pick are written into the boxes in the order the form prints them.
date field at person.date_of_birth, named “Date of birth”, drawn in sets of 2 + 2 + 4 printed boxes, part(1) first, and filled DD/MM/YYYY. The signer picks it from a calendar and the digits go into the boxes; it is the same field the editor makes when boxes are joined as one date.
- The value is its digits, in the order the boxes print them. 16 August 2026 is stored in this field as
16082026and sealed one digit a box. Send it as16082026, or as2026-08-16, which is laid into the boxes in the order the label states (16082026). - One set of boxes is
cells(8); parts are 2 + 2 + 4 (DD/MM/YYYYorMM/DD/YYYY) or 4 + 2 + 2 (YYYY/MM/DD). - The order is stated, never guessed. Write
order(...)on the tag, or on any one part, or state it in a label, asDate of birth (DD/MM/YYYY), or in Afrikaans, asGeboortedatum (DD/MM/JJJJ). A date tag withcells(...)and no order refuses the request.