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. The spouse’s surname is filled in by the main member, so that field’s role is Main Member and its subject is spouse. 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.
  • key is the machine name: main_member, spouse, dependant_1. 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: “Spouse”, “Dependant 1”. 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. In a POST /api/v1/templates request, labels that differ only in case count as the same, because a signer would read the two as one person; the editor’s rail refuses an exact repeat.
  • 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.

​
Addressing a field to a subject

A field is addressed by a pair: its subject and its data_key. first_name under spouse is a different piece of information from first_name under main_member, and the two never collide.
  • With a text tag, add subject(...) with the subject’s key, not its label: <<text:Main Member:subject(spouse):key(first_name):First name>>. 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. It does not report a subject’s presence, so keep your own note of which subjects you declared conditional.

​
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 main_member id_number fills the box on the application, 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.

​
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. Three parties can have a say, and each overrides the one before:
  1. The template. required means present; conditional means absent.
  2. You, when you create the envelope. subjects on POST /api/v1/envelopes is a map from subject key to true or false: { "spouse": true, "dependant_2": false }. A subject you do not name keeps the template’s rule. A key the template does not declare is refused, and so is false for a required subject; both are 400 invalid_request, and nothing is created.
  3. The signer. Beside each conditional subject’s section, the signing page 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. 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 every conditional subject you prefill. A value for a conditional subject you did not name as present 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 the template’s rule, 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 by the template’s rule when the envelope is sent, so the prefilled section opens hidden until the signer switches it on.
  • An envelope made without subjects, such as a batch row or an envelope sent from the dashboard, opens with every conditional subject absent. The signer switches on the people who exist.
  • ⚠️ 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 worked example

A medical aid application about a main member, a spouse and up to two dependants, signed by the main member 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 main member is on every envelope; everyone else may not be. (file is the document, base64-encoded; it is shortened here.)
POST /api/v1/templates
This member has a spouse and one dependant. The envelope says so, and prefills what your platform already knows:
POST /api/v1/envelopes
Thandi opens one document. Her own section, her spouse’s and Lerato’s are there, prefilled, and her ID number cannot be changed. dependant_2 is not named, so as a conditional subject it is absent: its fields are hidden and nothing in them is required. If she has a second child after all, she switches “Dependant 2” on and fills it in. Only Thandi is emailed, and only Thandi signs.

​
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 main_member subject, whose details the document holds, and the recipient in the Main Member 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.