Skip to main content
With no tags in the document, the page is measured instead: signature boxes, date fields, ID-number combs and marital-status questions are found where they already are, each coming back with its id. Detection places and types fields and groups tickboxes into questions, and every field and question it places is named as it is placed, as every field is (see Naming fields): from the vocabulary or the text printed around it where that says what it is, else with a numbered fallback. In the editor’s Find fields the names appear the moment the fields do; they are provisional until you save, when Vumasign numbers them from the template’s own counter and may give a better name from the printed text. Rename any of them with PATCH /api/v1/templates/{templateId}/fields or in the editor; renaming is optional. In the editor, detection is the first step of Set up this form, which starts by itself the first time a new template is opened and then works out the people and names the fields. Only find the boxes, on an empty template, and Find fields run detection on its own.
  • ⚠️ It is the same code the editor’s “Find fields” button runs, not a second implementation. A template authored through the API and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types — because it is one function, not two copies that currently agree.
  • It infers position and type. It cannot infer ownership: a page cannot say which of three signers writes in a box, so every detected field goes to the first role that is not a cc. Reassign them in the editor afterwards.
  • A label can imply a validation, and the boxes win. The validations detection infers from a label are email or phone. A field gets one only if its printed boxes could hold that kind of value; if they could not, the field keeps its boxes and gets no validation.
  • A label says what a box is for, in English or Afrikaans. A box whose printed label names a signature becomes a signature field, and one that names a paraaf an initials field, whether the form is printed in one language or both side by side (“Handtekening / Signature”). English “Initials” means two things, so it is read from where the box is: among a person’s details (“Title … Initials … Surname”) it is that person’s initials, a text field in their block; at the foot of each page, beside a signature, or asking to “Initial here” it is a signing initial. When nothing around it says which, it is a text field, because typing two letters is the cheaper mistake. The order the evidence is weighed in is below. A box beside a signature whose whole label is a date of signing is filled with the day it was signed, and so is one a few lines under the signature in the same column, with nothing between them but the signature’s own caption, one line (“Signed: ____” over “Employee”, then “Date: ____”), on a page with fillable fields too. A heading, a label of its own or another box between them starts another block, and a date with another signature just under it belongs to that one when that signature has no date of its own; a date that says anything more, such as a date of birth or a date received, is left for the signer. Some words name a signature only when they are the whole label: “Signed: ______” is where somebody signs, while “Signed at” asks for a place. A word with a negating word just before it (“Do not sign here”, “Geen handtekening”) is not read. A box the document itself declared as a checkbox, a choice or a signature keeps that type.
Its own label naming which of the names the initial is (first, last, middle, second, surname, eerste, tweede, middel, laaste, van, as in “First initial”) makes it a person’s initials too. Its own label saying where to initial (here, each, every, page, pages, hier), or opening with initial, parafeer and going on to say what for (to, om, as in “Please initial to confirm your identity”), outranks a name in that label, and a signature or signing date beside it outranks a name beside it. A box in the bottom 12% of the page or within 10% of either side, at the same place on more than one page, is a signing initial whatever is beside it; at the foot or the side alone, or repeated alone, it is one unless a name is beside it. So is a label that says whose initials they are (“Tenant initials”), two initials boxes on one row, and the word “Initial” on its own (“Initial”, “Please initial”). Anything else is a text field, unless the box is too short to type into.
  • A date in one set of printed boxes is a date only where the page states its order. The order is read from the letters printed one to a box: D D M M Y Y Y Y, M M D D Y Y Y Y, Y Y Y Y M M D D, or in Afrikaans, J for jaar, D D M M J J J J, J J J J M M D D. The boxes become a date field, which the signer fills from a calendar, when the label beside them also names a date: in words, or by stating its order in brackets, as (DD/MM/YYYY), (MM/DD/YYYY), (YYYY/MM/DD), (DD/MM/JJJJ), (JJJJ/MM/DD), in upper or lower case, with a slash, dash, dot, space or nothing between the parts. A box whose letters spell anything else, or a year of two digits, stays printed boxes the signer types into. No order is guessed. A date printed in several sets of boxes may state its order by either alone, its letters or its label, as below.
  • One answer printed in several sets of boxes is proposed as one field. A telephone number printed as a dialling code and a number, or a date as day, month and year, comes back as one field: one value, filled from the left, whose continuations are its later sets of boxes (see One value in several sets of boxes). Only the boxes and patterns below are joined, because a wrong join is worse than none: an amount printed as rands and cents is never joined here, and is offered by Set up this form instead (below). Join the rest in the editor (Several sets of boxes, one answer).
  • Which boxes: printed boxes on one page and one row, overlapping by at least 80% of the shorter one’s height, with heights within 25% of each other; at most 2 cells apart; with no other box between them; about the same subject; and said by the page to belong together. An AcroForm says so with its widgets’ names: the same name once the first number between underscores and the occurrence suffix are set aside, with consecutive occurrences (phonenumber_3_…_teleph-1, phonenumber_7_…_teleph-2). A drawn form says so when the row’s label is printed before the first box and each later box has no label of its own, the box before it standing between it and the row’s label; a later box too far from that label is not joined.
  • What is printed around them: nothing between the boxes but the punctuation the pattern is written with (a telephone number: - ( ); a date: / - .; an ID number: -; equal groups: -), and no currency just before the first box. Anything else printed between two boxes, such as a percent sign or a unit, keeps them apart.
  • Which cell counts: only these. Any other run of boxes stays separate fields.
  • Separated groups drawn on the page are offered, not joined. A branch code or a card number printed as equal groups of boxes with a separator between them is one answer, but a drawn page does not state it the way a fillable form’s widget names do. In the editor, Set up this form places those boxes separately and asks you whether to make them one answer. Template creation through the API leaves them separate.
  • Which boxes: 2 to 8 printed boxes on one row, by the row rules above, each of the same 2 to 4 cells, with the same separator, a dash (- – ‐ −) or /, printed in every gap; the first box labelled with one thing, and no later box labelled at all; and no currency just before the first box. A label printed in two languages, such as “Branch code/Takkode”, is one thing.
  • Never a range or a period: no label with any of these words: year, years, hour, hours, age, ages, range, period, between, duration, employed, start, end, begin, jare, ure, ouderdom, tydperk, tussen, duur, einde; and never two 4-cell boxes with a dash between them, which is a range of years.
  • What setup does: places the boxes separately and lists them in its review as a thing to check: “Three boxes that look like one answer. The signer would type it once.”, with Make it one answer (the editor’s join) and Keep separate. It never joins them by itself.
  • Rands and cents are offered as one amount. A form that prints an amount as a rands box, a decimal point or comma, and a short cents box is one answer, but filled from the left it would put the cents in the rands. Set up this form places the two boxes separately and asks whether to make them one amount. Accepted, the field takes one value, such as 12 345,67, and draws the rands right-aligned, ending at the printed separator, and the cents in their box (see One amount in rands and cents).
  • Which boxes: exactly two printed boxes on one row, by the row rules above, with one decimal mark, . ,, printed between them; the second box of 1 or 2 cells, fewer than the first; and a currency: one of R ZAR printed inside the first box or just before it, or the first box’s label naming one, as (R), (ZAR) or “in rand”. “Percentage [3] . [2] %” has no currency and is not offered.
  • What setup does: places the boxes separately and lists them in its review as a thing to check, “Monthly rental, rands and cents”: “Two boxes that look like one amount. The signer would type it once.”, with Make it one amount and Keep separate. It never joins them by itself, and template creation through the API leaves them separate.
  • A tickbox’s option is the wording printed beside it, a single letter included. Each box of a question is named by the words on one side of it, the same side for every box of that question: the side whose words name the boxes. A single capital letter or digit beside a box of a question is its option too, so “Gender M ☐ F ☐” and “Gender ☐ M ☐ F” are both a question with the options M and F, which name person.gender male and female. Words decide the side: in “1 ☐ Never 2 ☐ Sometimes” the options are Never and Sometimes, not 1 and 2. A single character beside a box on its own, such as the R of a rand amount, is not an option, nor is one only placed before the words it belongs to (”☐ R 0 – 5 000”).
  • A question is read from the page before the fillable form’s field names. A question’s name is the line printed to the left of its first option. When there is none, it is the first line above its options, over them or at their margin, that asks something: it ends in a colon or a question mark and is no other field’s label (a field to write in set beside it or just under it), with the line before it when it runs on in lower case (“Are they still a” over “member?”). On the way up, another question’s options and another field’s label are passed over, and any other line ends the search; only then is a question named after its fields’ names. One field name over two rows of tickboxes is two questions when each row prints its own question to its left, a sentence each at one margin and never an instruction (“Please tick one box only.”); a question that runs over two lines beside two rows, and a radio field, which the file itself declares one question, stay one.
  • A table’s cell with no label of its own is named by its row and its column. In a fillable table, three or more cells of one width stacked in a column, a cell with nothing printed beside it takes the heading printed over its column, after the row’s own heading when the row prints one just before its own table’s first cell (“Spouse”, “GP name”: “Spouse GP name”), and is typed from that name as any box is. A cell the file names in words keeps its own name, and the later part of an answer split over boxes, such as the cents beside a rand amount, takes no heading.
  • A grid of tickboxes the form asks you to pick one of is one question. On a fillable form whose tickboxes are separate fields, boxes laid out in two or more columns and rows, each with its own printed wording, under a line that asks for one choice (“Please select your health plan”, “Select one”), come back as one question that takes one answer, named by that line. Every tickbox between that line and the next paragraph at its margin must be in the grid, or none is. Boxes stay separate when the line asks for more than one (“one or more”, “for each”, “one for yourself and one for your spouse”), when another instruction or a second column sits beside or inside the grid, in a one-column checklist, and when a box has no wording of its own. Where the same wording appears in two columns, such as a plan offered in several series, each option is named by its own wording and its column’s heading, leaving out the words most headings share: on a grid of plans in several series, “Classic” under “Saver Series” is classic_saver, and “Classic Smart” under “Smart Saver Series” classic_smart_saver. The headings are read from a row of headings just over the grid, each starting where its column starts, and a heading run printed across two columns is split between them. A grid’s option whose wording is set on two lines in the same type beside its box is one option. When the headings cannot name every option differently, the options are named by the general rule, and two still alike are numbered: name them in the editor.
  • ⚠️ A document with nothing detectable is not an error. A flat scan with no text layer yields no fields, and the call still answers 201 with a template holding its roles and its document — which is the thing you then place fields on. fields being empty is how you tell.
  • A blank printed as underscores or dots is a field. A line of three or more underscores, or a leader of dots (“Name: ”, “Date …………”), is a box to write on. It is named by the words before it on its line. Failing those, it is named by a short caption printed just under it, as in a signing block (“” over “Signature”), when that caption is not a label with a blank of its own; failing that, by the line just above it when that line ends in a colon or a question mark (“If yes, give details:”) and the blank does not sit in the middle of a sentence. Its type comes from that name as a drawn box’s does: “Signed” makes it a signature, and a bare “Date” beside one its date of signing. Inside a table cell only that cell’s words are read. These are not fields: a blank that nothing names, a line across most of the page with no words beside it, a blank where the form already has a box or a fillable field, a leader of dots that runs to a page number or an amount (a table of contents, a statement), and a blank that shows it was written in, by text printed over it, an answer typed onto it or after its label’s colon, or a long number between two of its leaders.
  • Forms made in Word are read as tables. A cell with words in it is a label; an empty white cell beside it, or under a column heading, is a field named by that label. A pale tint still counts as somewhere to write; an empty cell shaded darker than that, a row that states a total, and a cell that already holds text or an image are not fields. A table drawn inside a cell of another table, as on a form laid out in one large cell, is read as a table of its own when its cells are ruled on every side and it has both a label and an empty cell: its cells are named by the cells around them in that inner table. Shading inside a cell, a cell left open where two rows read as one, and a row of character boxes are not such a table, and leave the cell as it was. A row of 2 or more empty cells, each one line tall, narrow, and under its own short option (“Male”, “Female”), is a question of tick boxes when those two rows hold nothing else, nothing to fill in lies under them, and the lines just above ask for a mark (“indicate with an ‘X’”, “tick”, “mark with”, “merk”); “indicate” or “select” alone asks for writing. When the line asks for several (“Tick all that apply”, “Merk alle”), each cell is a tick box of its own rather than one question. An option that asks for something written, such as “Name”, “Surname” or “Day”, keeps its cells somewhere to write.
  • A fillable form’s own fields are its fields. On a page where the PDF already has form fields, detection proposes those, and not the empty boxes or table cells drawn around them: a form that states where its fields are has drawn the rest for reading, such as a table comparing plans. The exception is the signing block: a box whose label names a signature or initials, because forms made for printing seldom make their signature lines fillable, and a box labelled only as a date beside such a signature, which is filled with the day it was signed. A page that has none of its own form fields is measured as before, so a form that made only some of its pages fillable still gets fields on the others. A read-only form field, a button, or the invisible signature a signing service adds to a signed document does not make a page fillable.
  • Repeated rows become subjects. Two or more identical rows of empty cells under a heading that names a person — “Beneficiary details” — are proposed as one subject per row: beneficiary_1, beneficiary_2, and so on, each row’s fields carrying its subject’s key. The subjects are added to the template unless you already declared that key; if a proposed subject’s label matches one you declared under another key, it is not added and its row’s fields come back with no subject.
  • Each detected subject is conditional: absent unless somebody says it is there. Name the ones an envelope is about in subjects when you create it — { "beneficiary_1": true, "beneficiary_2": true } — and the other rows are hidden from the signer, not required, and left empty on the sealed page, as they would be on paper. See Subjects.
  • ⚠️ A document that already holds somebody’s details comes back with a warning. If the upload contains South African ID numbers that pass their checksum, email addresses, phone numbers, or a signature image in a signature cell, the response’s warnings says how many of each — never which — because every envelope sent from the template would carry them. The template is still created. Upload the blank form instead.
  • The same warnings are on the template whenever you read it with GET /api/v1/templates/{templateId}, including a template somebody uploaded on the dashboard, and one made on the dashboard with Save as template from a one-off, whose documents are checked the same way when it is saved. On the dashboard a person must acknowledge a personal-information warning before the template is opened or sent, while an xfa-form warning is shown at upload and needs no acknowledgement; the API does not ask. If you send templates your users uploaded on the dashboard, read their warnings first: sending one is your decision, and the signers receive whatever is on it.

What setup makes required

Set up this form decides which of the boxes it found must be filled in. It decides once, at the end of its run, when it knows whose each box is and what each is called, and the first rule that fits a box decides it: A plain Yes or No must be answered. A question detected from two tickboxes, one printed with a yes and the other with a no, is required: a signer must tick one. An option’s words are one of these, or several of them set apart by a slash (“Ja / Yes”): It stays optional when an option or the question says it is optional or applies only “if applicable”, when the section heading over it says it is optional (“MARKETING PREFERENCES (OPTIONAL)”), when a line between the question and its options starts with a condition and says what to fill in, and when the question is asked only after another answer (“If yes, …”). A section’s “if applicable” asks whether a person is on the form, so it is not read here. A question of a person who may not be on the form is asked only while that person is, so it must be answered only then (see Present or absent). Setup decides it at the end of its run, with the other boxes, and leaves it optional when it cannot tell whose the question is, as it does a name; Find fields on its own leaves it as found. Through the API it is required only when one role signs, as the other defaults are. A longer list of options stays optional. Every signature of a person setup found, wherever they sign. One person often signs a form several times. Every signature box on the role of a person setup found is required, however many there are, bare ones such as “Signature”, “Full name and signature” or “Signed at” included, and the review says how often each person signs (“Main member signs 5 times.”), asking nothing. A box is left optional and listed only when it is somebody else’s:
  • Its caption names anybody but the signer, wherever the word sits. The signer’s own words are the role’s name, the heading of their part of the form, and, on the main person’s role, the main person’s words such as “main applicant”, “member” or “tenant”. Any other person or office in the caption, brackets included, makes it somebody else’s: “Applicant (witness)”, “Tenant surety signature”, “Signature of interpreter”, “Doctor’s signature”, “Received by”, “Approved by”, “For and on behalf of”. This holds even when setup placed the line in the signer’s part of the form, and even when the main person is named too: “Signature of applicant or witness” is the witness’s.
  • Another person’s word on another person’s role. “Signature of tenant” on the landlord’s role, or “Patient signature” on the doctor’s, is the person it names.
  • A party who signs for the main person, such as an account holder, a premium payer or a guardian. On a role’s only signature line it is the signer: a debit order’s “Signature of account holder” is required. Beside the signer’s other lines it is listed, since it may be a third party’s: “Account holder signature” next to the main applicant’s. Named as the signer’s alternative, joined by ”/”, “or” or “of” (“Signature of policyholder / premium payer”, “main member / guardian”), it is the signer’s line, however many there are.
  • A table row, a column or a section names somebody else. In a table whose rows are people, such as “Patient”, “Doctor” and “Interpreter” under a “Signature” column, each box takes its row’s heading as its label, so the patient’s line is required and the others are listed. A “Signature” in a “Doctor” column, or a bare “Signature” under “FOR OFFICE USE ONLY”, is read with its column’s or section’s heading in the same way. The main applicant’s lines under “Declaration by main applicant” stay theirs.
  • Another numbered or lettered party. “Signature of Party B” on Party A, and “Tenant no. 2”, “Tenant two”, “Second tenant” or “Tenant #2” on Tenant 1, are two people.
  • A role’s only signature line is its signer’s in a word setup does not know as a person (“Signature of client”, a debit order’s “Signature of account holder”). A word it does know, such as “witness” or “doctor”, still makes it somebody else’s. Of several lines on a role, an unknown word does too.
Initials whose caption names somebody else, such as “Doctor’s initials”, are read the same way. Plain “Initials” are the role’s. Names, initials and dates of birth, for each person. These are required for everybody the form names: the person who fills in each role’s own boxes, and each subject, such as a co-tenant or a next of kin. The initials of a name are a typed answer, not the initials a signer marks a page with, which are decided with the signatures. A title stays optional. One box for an ID or passport number, which takes whichever the person has, is required like a surname. Separate ID number and passport number boxes are left optional, because a required South African ID number would stop every signer who has none, and a required passport number every signer who has an ID number instead. On a template, setup lists them in its review, the ID numbers and the passport numbers as an item each, with Make required, which makes them all required in one step, and Keep optional; that choice is kept for every envelope. On a one-off, it says how many it left optional under Who signs, and offers Make required?. What the form says about that box, and nothing wider. A box is optional, or required, by the form’s own words when they are its label, its tooltip, its column’s heading in a table, or the words printed just after it on the same line when those words say nothing else. A section heading is never read this way: “Section B: Co-tenant (if applicable)” asks whether there is a co-tenant, which is a question about the person, not about each box. A column heading can make a box optional but never required, and asterisks are not read. A box that says both is optional. A line that starts with a condition and says what to fill in. When the first sentence of the line printed just above a box, in the box’s own column, or of the box’s own label, starts with a condition and is an instruction about the boxes under it, the box is asked only in some cases, so a box of the main signer is left optional. An instruction opens the clause after the condition’s comma with one of the verbs in the table below, perhaps after “please” (“If yes, please attach a copy”), or says what the one filling the form in must do (“If we are paying a third party bank account, the main member must insert the ID or passport number of the third party”). A verb inside the condition (“If you complete this form online, we will contact you”) or in what somebody else will do (”…, we will provide a card”, ”…, the landlord shall provide a refund”) makes no instruction. A line with no instruction is read only when it ends with a colon (“IF YOU ARE SIGNING ON BEHALF OF A COMPANY:”), and such a line never makes the main person’s own names or date of birth optional. A line with no comma and no closing colon (“If over 18 years provide cellphone number”) is not read, nor is an emergency (“In case of emergency, contact:”). A numbered or lettered start, such as “1.1” or “(a)”, is read past. On the box of a person who may not be there, such as “If there is a co-tenant:” over the co-tenant’s names, the condition is whether that person is on the form, so it is read as “if applicable” is (below). It is never read on a signature or initials box, whose line is usually its declaration (“If you agree to the terms above, please sign below.”): whose signature it is decides alone. Nor is a statement read this way, nor a condition that starts a later sentence of a paragraph (“This agreement ends on termination. If the Tenant fails to pay rent”), a line that asks a question (“If yes, what is the diagnosis?”), or a condition in the middle of a heading (“About your spouse (complete only if married)”). Only the nearest line reaches the box: one over a whole block leaves its first row optional and the rest as they would otherwise be. A question’s options read only a line printed between the question and them, never the previous question’s “If yes, attach…” above it. Every language below is read on every box, so a bilingual form’s “Optional / Opsioneel” is read in both. A phrase is not read when a negating word of its own language comes just before it (“not optional”), and a required word is not read when the words around it state a condition (“required if married”) or ask a question: “If applicable” on a person who may not be there. On the co-tenant’s own box, “Co-tenant date of birth (if applicable)” means “if there is a co-tenant”, so those words are set aside and the box is decided like any other of the co-tenant’s: required. A line over the co-tenant’s boxes that starts with a condition, such as “If there is a co-tenant:”, is set aside the same way. A required box of a person who is not on the envelope is never asked for. It counts only while that person is on the form (see Present or absent). When setup cannot tell whose a box is. Setup finds people by the words a form prints, and does not know them all: it may finish with every box on one role. So wherever it can see that a box may belong to somebody else, it leaves the box optional, whatever the form prints beside it, and lists it:
  • a signature box addressed to another person, by setup’s people or by its own words, such as the tenant’s role holding the co-tenant’s, or “Signature of account holder” on the main applicant’s;
  • every signature and initials box of a role setup matched to nobody that holds more than one signature box, since a tenant’s role holding the landlord’s and the co-tenant’s signatures too looks the same as one holding only the tenant’s, and initials boxes of one role that share a page, such as a footer’s “Tenant ___ Landlord ___”;
  • the boxes of a role that does not sign, such as an approver listed first, which holds them only because every box starts there;
  • a name, date of birth, ID number or passport number one person holds twice in a document, such as “First names” and “Surety full names” both left with the tenant, since that is two people setup did not tell apart. When exactly one of the two sits on a page among that person’s other details, such as their first names beside their surname, that one is theirs and required, and only the stray one, such as a bare “Name” under an employer’s warranty, is left optional. One box for an ID or passport number counts as held twice beside any other ID or passport number box of the same person, such as a referee’s “ID / Passport number” left with the employee beside their own “ID number”. Make required? is offered only for ID and passport numbers it could tell apart, and for ID numbers and passport numbers separately, since requiring both of one person stops everybody who has one and not the other;
  • the boxes of a person setup found but did not place, which the review lists.
Setup can only see what the page shows it. A box of somebody it found no trace of, whose words name nobody, is decided as its role’s own when that role holds nothing else like it or setup matched the role to a person: a bare “Signature” on the main applicant’s role is theirs, however many there are. So check what setup made required against the form before you save. What it never changes. Only the boxes setup found in that run are decided. A box you made required or optional while setup was running stays as you set it, and so does every box that was already on the template when it started. Nothing is decided again later: a box you rename to a date of birth afterwards keeps whatever it was. Stopping setup before it has worked out the people leaves only the boxes the form marks required in words; stopping it while the AI is naming fields still applies the defaults. Undo setup takes them back with the rest. Naming fields, in the editor or without it, never changes whether a field is required. Find fields on its own knows nobody, so it takes only the form’s own words, and never on a signature. It leaves every signature optional, and says how many before you add them. Through the API, a template created from a document gets the same rules for the boxes detection places when the template has exactly one role that signs, since every detected box goes to that role. When more than one of its roles signs, or an approver is listed first, nothing detection places is made required, not even by the form’s own words, because nothing says whose each box is. With one, the rules apply with what the API knows: the names it gives, and the subjects you declared or detection found in a table. A signature or initials box is required only when the document has one signature box. A box outside a detected table belongs to no subject, so “(if applicable)” on it reads as the main signer’s own and the box is optional, and a spouse’s name printed beside the main signer’s leaves both optional, as two people on one role. A text tag says for itself whether its field is required, and the rules do not apply to it.

Shown when Yes or No

A form often prints the details it wants under a Yes or No question, for the signer who gives one answer: “Have you had an operation? Yes No”, then “If yes, please give details” and a table of operations; or “Are you a South African citizen? Yes No”, then “If no, passport number”. On a template, Set up this form offers a rule for those boxes in its review: “Shown only when the question is Yes”, or ”… is No” for boxes that say “If no”. The review’s item is named by what the form prints, and says how many boxes there are: by the question’s number when it has one (“11.18 table, 12 boxes”, or “Under 4.2 (Yes), 1 box” for boxes that say “If yes”), else by the table’s caption, else by the section the question is in, else by its page (“12 boxes on page 12”). Boxes that say “If yes” or “If no” are named with the answer, so a question’s two items never read alike. It never writes the rule on its own:
  • The item’s page link selects the boxes on the page, so you can see which they are.
  • Looks right writes the rule on the boxes. They are hidden unless the question has the answer the rule names.
  • Always show writes nothing, and the offer goes.
The question is one of two options, printed with the same yes and no words a plain Yes or No is read by, above. Setup offers a rule for only two things under it, in its column on the same page:
  • A table directly under the question that says it is the question’s details. Something must ask for the details:
    • the line just above its column headings, or its caption, starts “If yes”, “Details”, “Particulars” or “Besonderhede” (or “Please give details”);
    • the question itself ends by asking for them (”… please give details”, “please specify”);
    • or a line at the top of the question’s section says so for every question in it (“If you answered ‘Yes’, please provide full details”), up to the next section heading.
    Between the question and the table there may be only the rest of the question’s own words, its “Example: …” (or “e.g.”, “Byvoorbeeld”) lines, that one line, and the table’s column headings, however many lines they wrap over. The offer is the whole table, every box among its rows, and a table that runs on to the next page is not offered.
  • Boxes whose own words say when they are asked: “If yes”, “If so” or “Indien ja” are offered as shown only when the question is Yes. “If no,”, “If not,” or “Indien nee,” are offered as shown only when it is No, and only where the words stop there: “If no other income” is not read. They run down from the question for as long as each box says one of these.
A box with no such words is never in an offer, however close it is to the question: “Surety full names” under “Is there a surety?” stays as it is, and so does a dependants table under “Are you the main member?”. When it is unclear which question the boxes belong to, setup offers nothing: not for a question with another Yes or No question directly above it (“1. Heart disease? 2. Diabetes? 3. Cancer?”, then “If yes, give details”), not for boxes that say “any of the above”, and not for boxes two questions both reach. A question printed inside a table’s row, and a box in the page’s footer, are never read this way. Setup offers nothing when any of the boxes already has a rule of its own, when the question is answered by another role than the boxes, or when the rule would make a loop of rules. Signature and initials boxes, the date signed and the signer’s own details are never in an offer: they stay shown, and the review says so. For anything setup does not offer, give the boxes a rule yourself, in Shown when. An offer is about the boxes and the question as they were when setup made it. Moving, resizing or retyping one of them, giving one other cells (joining it to other boxes, for one), or giving the question another option, ends the offer without a word; undoing that change brings it back, and so does undoing Looks right. Undo setup takes back a rule you accepted with the rest of setup’s steps. A one-off envelope’s setup makes no such offer. A box its rule hides is not asked for, so a required box the signer never sees never stops them finishing. Setup locks no box, so the rule does not stop the envelope being sent either.

Which roles setup makes optional

Every role setup makes is required unless the form says otherwise, because the two mistakes cost different amounts. A role wrongly required is refused at send, by name, and one click fixes it. A role wrongly made optional lets an envelope go out without a signature it needed, and nothing says so until somebody reads the sealed copy. So setup proposes a role that can be left out only when all of these hold:
  • the role is a party’s, never a witness’s. Whether a form can do without its witness is a legal question for whoever sets up the template, so “Second witness (if applicable)” stays required until somebody chooses otherwise;
  • it is not the form’s main person: not the person the form is about, not the person whose details are the form’s required subject, and not the template’s first role that signs;
  • each of its signature lines is marked optional or “if applicable”, in the words below and in any of their languages, by the line’s caption or by the section heading the line sits under, and nothing there says it is required. A person with one line marked and another not, such as an unmarked declaration, stays required. “Broker signature (if applicable)” and “Afdeling F: Makelaar (indien van toepassing)” make the broker optional. The words count only where they stand on their own, as in “(if applicable)” or “Broker: optional”, so a heading “Optional benefits” or a caption “Signature of spouse accepting optional benefits” makes nobody optional. A line that hands the section to the person only on condition that they exist counts too: “If you already have a financial adviser, please ask them to complete this section” makes the adviser optional when every one of their signature lines sits in such a section, in its own column. The condition must name the person and end at a comma or colon; “If you are employed, your employer must complete this section” is about the applicant and makes nobody optional.
The person’s card says which words did it, for example “creates role Broker, which an envelope can leave out: its signature caption “Broker signature (if applicable)” says “if applicable””, or “the line that hands it its section “If you already have a financial adviser, …” says “If you already have a financial adviser””, and Can be left out of an envelope on the card takes it back before you apply it. Once the template is saved, change it under Who signs. Setup decides this only for a role it creates. A role the template already has keeps whatever it is, so running setup again never changes a role somebody marked required or optional. One-off envelopes have no optional roles, so setup proposes none there. A person decision through the API makes a new role required unless it says role_presence.