Skip to main content
Write the field into the document where it goes. Upload it, and the field is already there, already assigned to the right signer, with nobody opening an editor.
Types: 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.
The signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, the signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it. 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 .docx is 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.
On a one-off envelope, tags are the only way a field gets onto the page. The envelope is refused only when none of its documents places a field: an annexure with no tags is accepted beside a document that has them. Every directive, and what each refusal says, is on 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 says question(...), 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:
Several choices — 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(...) and ask(...) 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 an option(...) of male, female and 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 no optional (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.
These two tags are one field at 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(...) without part(...) is one row of boxes: <<text:Employee:ID number:cells(13)>>.
  • A part needs both cells(...) and key(...): 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 single cells(...) 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.
These three tags are one 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 16082026 and sealed one digit a box. Send it as 16082026, or as 2026-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/YYYY or MM/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, as Date of birth (DD/MM/YYYY), or in Afrikaans, as Geboortedatum (DD/MM/JJJJ). A date tag with cells(...) and no order refuses the request.