Skip to main content
A form can ask about people who never sign it. A medical aid application wants the main member’s details, their spouse’s and each dependant’s, and only the main member signs. Vumasign keeps those two kinds of people apart. A role is a recipient slot, and whoever fills it signs, approves or receives a copy. A subject is somebody the document is about. Dependant 1 is a subject, and nobody has to be a recipient for them. That is how one application can collect details for a whole family and be signed by one person, and how the same template can go to a member with no spouse without asking them for a spouse.

A role acts; a subject is described

A field has both. On a lease, the co-tenant’s surname is filled in by the tenant, so that field’s role is Tenant and its subject is co_tenant. A field with no subject (subject is null) belongs to the document itself, like a policy number, or to the person signing it.

Declaring subjects on a template

Declare them in subjects on POST /api/v1/templates, or add them in the editor’s Subjects rail. Each has three parts, and through the API an optional fourth, starts_as (below).
  • key is the machine name: tenant, co_tenant, surety. It must match the pattern ^[a-z0-9_]+$ and be at most 100 characters, and it is not lower-cased for you: Spouse is refused, and the refusal names the key that would be accepted. A key never changes once it exists, so it is the thing to match against your own records.
  • label is what people read: “Co-tenant”, “Surety”. At most 200 characters (UTF-16 code units, after Unicode composition), never blank. It can be renamed at any time and the key stays put. Each subject’s label is its own, and labels that differ only in case count as the same, because a signer would read the two as one person. That holds everywhere: a POST /api/v1/templates request and the editor’s rail refuse the same labels.
  • presence is required or conditional, and it is optional, defaulting to required. More on this below.
A template declares at most 200 subjects. In the editor, the word beside each subject, “every envelope” or “only some envelopes”, is both its presence and the control that changes it.

Ask the signer, include, or leave out

A lease may or may not have a co-tenant, and the sender often does not know. So each conditional subject has one more setting: how the person starts on an envelope sent from the dashboard. The same three choices, in the same words, are on a template’s Subjects rail, on a one-off’s Who this form is about, and in Filling in before sending.
  • A required subject has no choice: it is always on the form. A one-off’s Who this form is about says “Always on this form” beside it.
  • A subject added in the editor starts as Ask the signer, whether you add it on the Subjects rail, Find fields proposes it, or Set up this form finds it, on a template or a one-off. A person setup makes both a signer and a subject starts as Include, because the person signing is the answer.
  • A subject declared through the API starts as Leave out unless the request says otherwise, which is how every subject behaved before the choice existed. So does every subject that existed before it. To choose, give starts_as (one of the values in the table) on each entry of subjects in POST /api/v1/templates, or on a person decision. Omitted, a subject the request creates is absent, and a decision about an existing subject keeps its choice. It is ignored for a required subject. A template’s subjects say each one’s presence and starts_as when you read it.
  • The signer reads the subject’s label in the question, and no question text is stored. So under a subject set to Ask the signer, the editor suggests renaming a label that looks like a key (co_tenant), is a single character, or is only a word such as “Person” or “Other” and a number.
  • The editor also warns when no box belongs to the person yet, for example “No box on this form belongs to Surety yet, so nobody will be asked.” A box belongs to them when it is addressed to them or shown only for them. Nobody would be asked, so the send leaves such a person out.
  • The choice applies to envelopes sent from the dashboard, one at a time or in bulk. An envelope created through the API does not take it for the people it records when it is created (below).
  • A draft takes the template’s choice when it is made, and keeps it if the template changes afterwards. Change it on the draft in Fill in before sending.

What the signer is asked

The signer who holds the person’s section is asked first, in a “Who is on this form?” panel at the top of the signing page. They can read the document below it, but they cannot fill anything in, and they cannot finish, until every question is answered. No answer is chosen for them.
  • One question per person, worded from their label. A key-shaped label is turned into words, so a signer never reads co_tenant.
  • One count for a numbered family. People asked of the same signer whose keys share a stem and run in order (sibling_1, sibling_2, sibling_3), and whose labels are the same apart from the number, are asked “how many”. An answer of 2 puts the two lowest-numbered on the form and leaves the rest out.
  • Who holds the section is a recipient with a field about the person, or a field the section shows or hides, and never a cc. When several hold it, the first answer settles it, and the others see it settled on the page. A recipient who holds none of it is not asked.
  • A person who signs this envelope is not asked about themselves. Setup starts a person who also signs as Include, and so does the editor when a person card gives a role to someone whose subject was made elsewhere (on the Subjects rail, or by another person card) and is still set to ask, as long as that role still signs when the template is saved; a subject you set to leave out stays left out. The send includes a person a recipient signs for in a role that stands for the same person: on an envelope made from a template, the template’s role, and on a one-off, the Who signs row setup made for them.
  • A person no box belongs to is left out when the envelope is sent, and nobody is asked.
  • An answer is not a lock. The signer can still switch the section on or off afterwards with the control described below, until somebody who holds it has finished.
  • Each answer is recorded in the envelope’s history, with the question as the signer read it, and the sealed certificate says who this form is about and how that was decided (Sealing).

Subjects on a one-off

A one-off envelope set up in the editor has subjects too. Set up this form finds the people a form describes. A co-tenant or a surety whose section holds their own details becomes a subject, such as co_tenant, so their surname is never read as the tenant’s. The editor lists them under Who this form is about.
  • A subject set up this way is conditional, and it starts as Ask the signer, or Include for a person who also signs, as above.
  • Ask the signer is not offered for a person who also signs: the Who signs row setup made for them stands for them, and a save that chooses it is refused. The row keeps standing for them when you change the name or address on it.
  • Change the choice beside each one. While a person is Leave out, or until the signer answers that they are on the form, their boxes are hidden from the signer and are not required, exactly as described below.
  • Save as template keeps the subjects and each one’s choice, so the template’s next envelope knows who’s who and asks the same questions. It does not keep which people were on this one-off, or what its signer answered.
  • GET /api/v1/envelopes/{envelopeId} shows any envelope’s subjects in subjects: each one’s presence, whether it is present, whether the signer is still to be asked (awaiting_signer), and the sender’s choice (starts_as). While a question is open, present is false, which is what the signer sees, and awaiting_signer is true.
An envelope created through POST /api/v1/envelopes/one-off declares no subjects, because its fields come from text tags.

Addressing a field to a subject

A field is addressed by a pair: its subject and its data_key. person.first_names under co_tenant is a different piece of information from person.first_names under tenant, and the two never collide.
  • With a text tag, add subject(...) with the subject’s key, not its label: <<text:Tenant:subject(co_tenant):key(person.first_names):First names>>. A tag naming a subject the template does not declare refuses the whole request, as an unknown role does. See Text tags.
  • In the editor, select the fields (drag a box around a whole section to select it at once) and pick the subject from the Subjects rail. A detected field has no subject until you give it one.
  • In the template response, GET /api/v1/templates/{templateId} reports every field’s subject and data_key, and lists the template’s subjects by key and label, each with its presence (which ones are conditional) and its starts_as.

Filling a subject’s fields from an envelope

values on POST /api/v1/envelopes is a list of triples: values[].subject, values[].key and values[].value. The subject and key together are the address, and an address names a set of fields: every field at that address gets the value. One tenant person.sa_id_number fills the box on the lease, the box on the declaration and any other box with the same address. Use null as the subject for a field that has none. A subject the template does not declare is refused as value_subject_unknown, and an address that matches no field is refused as value_address_unknown. To find every such mismatch in one request without creating anything, see Checking values before you send.

Present or absent

Each envelope records which of the template’s subjects it is about.
  • A required subject is on every envelope, and nobody can switch them off: a medical aid application is always about its main member.
  • A conditional subject may be left off. A conditional subject is absent unless somebody says they are there.
A field addressed to an absent subject is hidden and not required, automatically, without a condition. Leave the spouse off, and every spouse field disappears from the signing page and stops blocking completion. The paper itself is unchanged: the printed “Spouse details” section is still on the sealed page, empty, as it would be on a paper form left blank. That includes the signing date, name and email Vumasign stamps when somebody signs: a box hidden from the signer, by an absent subject or by a condition that is false, is not stamped. Three parties can have a say, and each overrides the one before:
  1. The template. required means present. A conditional subject starts as the sender chose (above) on an envelope sent from the dashboard: asked about, included, or left out.
  2. You, when you create the envelope through the API. subjects on POST /api/v1/envelopes is a map from subject key to true, false or "ask": { "co_tenant": "ask", "surety": false }. "ask" asks the signer at the start of signing, as above; true and false settle it with no question. ⚠️ A conditional subject you do not name is left out, and the signer is not asked about them, whatever the template’s choice is. An integration that already knows who is on the form never has its signers asked again. A key the template does not declare is refused, and so are false and "ask" for a required subject; each is 400 invalid_request, and nothing is created.
  3. The signer. They answer the question if they are asked. Beside each conditional subject’s section, the signing page also offers a control labelled from the subject’s name, such as “Add spouse details”, and the signer can switch the section on or off. It is offered to a recipient who has fields about that subject, and never to a cc.
⚠️ Your declaration is a default, not a lock. There is no way for you to stop a signer switching a conditional subject either way, until somebody who holds that section has signed it (below). That is deliberate: a dependant can turn out to be over the scheme’s age limit, and neither the template nor your platform can know that when the envelope is created. Every switch is recorded in the envelope’s audit history, so the record says the signer declared there was no spouse rather than leaving the section blank. ⚠️ Once somebody has signed a section, nobody can switch it. A recipient holds a section when they have a field about that subject, or a field the section shows or hides. When any recipient who holds it has finished (a status of signed or approved), the section is frozen in both directions, so what they signed never changes. The signing page shows the control disabled and says why. A signer who thinks the section is wrong declines the document, and you void it and send a new one. A recipient who finished without holding the section does not freeze it. ⚠️ A page that is out of date cannot be signed. A signer’s page shows the sections as they were when it was drawn, so if another recipient switches one while it is open, it is showing a different document. When the signer finishes, the signing page sends which of the envelope’s sections were present as far as it knew, including sections it does not show this signer, and if they no longer match the envelope the document is not signed and nothing from that attempt is saved: the signer is told the document changed while they had it open, the page shows or hides each section as it now stands, keeping what they typed elsewhere, and they check it and finish again. This is the same for a recipient who approves, and for a section switched on or off. A switch and a finish that arrive together are taken one at a time: if the switch lands first, the finish is refused this way, and if the finish lands first, a section the finisher holds is frozen and the switch is refused. A section they do not hold can still be switched after they finish, as above. When a section is switched off, every answer in it is removed so nothing that was not asked is sealed. Because of the freeze, those answers only ever belong to recipients who have not finished yet. Switching the section on again restores only part of it.
  • A value you locked is put back for every recipient who has not finished yet (a status of pending, sent or opened).
  • Nothing a recipient typed is put back. The signer who switches the section on still sees their own answers on screen until they reload, and their next save stores them again. Anybody else with fields in the section fills them in again before they finish.
A few things follow from this.
  • ⚠️ Name as true or "ask" every conditional subject you prefill. A value for a subject you ask about is kept: it is shown if the signer answers Yes and removed if they answer No. A value for a conditional subject you named neither way is handled in one of two ways, and which depends only on whether subjects is in the request at all:
    • subjects sent, even {}: the subject is absent, by false or by not being named, so the value contradicts the request and is refused as invalid_request. Nothing is created.
    • subjects omitted: the value is accepted and stored, but the subject is absent when the envelope is sent, so the prefilled section opens hidden until the signer switches it on.
  • An envelope made through the API without subjects, such as a batch row, opens with every conditional subject absent, and nobody is asked. The signer switches on the people who exist. If the draft is then sent from the dashboard, the sender can choose for each one first, in Filling in before sending.
  • ⚠️ An envelope records who it is about once, and keeps it. Changing a subject’s presence in the editor reaches only an envelope that has not recorded it yet: one sent afterwards, or a draft made without subjects, which records it when it is sent. An envelope already sent keeps what it was sent with. So does a draft created with subjects, even {}: it recorded every subject when it was created, and sending it later changes none of them. A subject’s Ask the signer, Include or Leave out is a draft’s own from when the draft is made.

A worked example

A residential lease about a tenant, and perhaps a co-tenant and a surety, signed by the tenant alone. The document carries tags like these, written in white so they do not print:
Tags in the document
The template declares one role and the subjects. The tenant is on every envelope; the co-tenant and the surety may not be. (file is the document, base64-encoded; it is shortened here.)
POST /api/v1/templates
Your platform knows this lease has a co-tenant. The envelope says so, and prefills what you already know:
POST /api/v1/envelopes
Thandi opens one document. Her own section and Sipho’s are there, prefilled, and her ID number cannot be changed. surety is not named, so it is left out and Thandi is not asked about a surety: its fields are hidden and nothing in them is required. If there is a surety after all, she switches “Surety” on and fills it in. Only Thandi is emailed, and only Thandi signs. Sent from the dashboard instead, with the co-tenant set to Ask the signer in the editor, the same template would first ask Thandi “Co-tenant: is there one on this form?”, and show Sipho’s section only if she answers Yes.

What a subject is not

  • Not a recipient record, though the same person can be both. A subject and a recipient are two different records. The subject record has no email address, and it is never emailed, given a signing link or asked to sign: whoever fills in the section does it under their own role. The same human can be both. In the worked example, Thandi is the tenant subject, whose details the document holds, and the recipient in the Tenant role, who signs it. She is emailed and signs as the recipient, not as the subject.
  • Not a count the signer chooses. The template fixes how many subjects there are, as the paper fixes how many rows it prints. A family with more dependants than the form has room for cannot add one.
  • Not a heading the signer reads by key. The signing page names a subject by its label, never by its key.
  • Not a condition, though a condition can read one. A subject hides its own fields with no condition written. For anything finer, a condition set in the editor can test whether a subject is present or absent.