> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vumasign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subjects

> The people a document is about, as distinct from the recipients who act on it.

export const completedRecipientStatuses = "signed or approved";

export const liveRecipientStatuses = "pending, sent or opened";

export const subjectToggleExample = "Add spouse details";

export const presenceConditionalWording = "only some envelopes";

export const presenceRequiredWording = "every envelope";

export const defaultPresence = "required";

export const subjectKeyPattern = "^[a-z0-9_]+$";

export const routingCc = "cc";

export const routingApprove = "approve";

export const routingSign = "sign";

export const presenceConditional = "conditional";

export const presenceRequired = "required";

export const valueAddressUnknownCode = "value_address_unknown";

export const valueSubjectUnknownCode = "value_subject_unknown";

export const invalidRequestCode = "invalid_request";

export const invalidRequestStatus = "400";

export const subjectLabelMax = "200";

export const subjectKeyMax = "100";

export const subjectLimit = "200";

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](/concepts/roles-and-recipients) 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

| | Role, filled by a recipient | Subject |
| - | - | - |
| Declared on a template | `roles` | `subjects` |
| On an envelope | a recipient, with a name and an email address | on this envelope or not, and nothing else |
| Emailed | as the envelope routes them, unless embedded | never as a subject |
| Acts on the document | signs (<code>{routingSign}</code>), approves (<code>{routingApprove}</code>) or receives a copy (<code>{routingCc}</code>) | never as a subject: the subject record signs nothing, approves nothing and is sent nothing |
| On a field | `role`: who fills the box in | `subject`: whose information the box holds |

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`](/api-reference/create-template), 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 <code>{subjectKeyPattern}</code> and be at most {subjectKeyMax} 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 {subjectLabelMax} 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`](/api-reference/create-template) 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 <code>{presenceRequired}</code> or <code>{presenceConditional}</code>, and it is optional, defaulting to <code>{defaultPresence}</code>.
  More on this [below](#present-or-absent).

A template declares at most {subjectLimit} subjects. In the editor, the word beside each subject,
“{presenceRequiredWording}” or “{presenceConditionalWording}”, 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](/concepts/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](/concepts/field-detection) field has
  no subject until you give it one.
* **In the template response**, [`GET /api/v1/templates/{templateId}`](/api-reference/get-template)
  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 <code>{presenceConditional}</code>.

## Filling a subject’s fields from an envelope

`values` on [`POST /api/v1/envelopes`](/api-reference/create-envelope) 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 <code>{valueSubjectUnknownCode}</code>, and an address that matches no field is refused
as <code>{valueAddressUnknownCode}</code>.

## Present or absent

Each envelope records which of the template’s subjects it is about.

* A **<code>{presenceRequired}</code>** subject is on every envelope, and nobody can switch them off: a medical aid
  application is always about its main member.
* A **<code>{presenceConditional}</code>** 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.** <code>{presenceRequired}</code> means present; <code>{presenceConditional}</code> means absent.
2. **You, when you create the envelope.** `subjects` on
   [`POST /api/v1/envelopes`](/api-reference/create-envelope) 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
   <code>{presenceRequired}</code> subject; both are {invalidRequestStatus} <code>{invalidRequestCode}</code>, 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 “{subjectToggleExample}”, 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 <code>{routingCc}</code>.

⚠️ **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 {completedRecipientStatuses}), 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](/api-reference/create-envelope) is put back for every recipient who has
  not finished yet (a status of {liveRecipientStatuses}).
* 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 <code>{invalidRequestCode}</code>.
    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](/api-reference/create-envelope-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:

```text Tags in the document theme={null}
<<text:Main Member:subject(main_member):key(first_name):First name>>
<<text:Main Member:subject(main_member):key(id_number):ID number>>
<<text:Main Member:subject(spouse):key(first_name):First name>>
<<text:Main Member:subject(spouse):key(id_number):ID number>>
<<text:Main Member:subject(dependant_1):key(first_name):First name>>
<<text:Main Member:subject(dependant_2):key(first_name):First name>>
<<sig:Main Member>>
```

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.)

```json POST /api/v1/templates theme={null}
{
  "file": "JVBERi0xLjcK",
  "name": "Medical aid application",
  "roles": ["Main Member"],
  "subjects": [
    { "key": "main_member", "label": "Main member", "presence": "required" },
    { "key": "spouse", "label": "Spouse", "presence": "conditional" },
    { "key": "dependant_1", "label": "Dependant 1", "presence": "conditional" },
    { "key": "dependant_2", "label": "Dependant 2", "presence": "conditional" }
  ]
}
```

This member has a spouse and one dependant. The envelope says so, and prefills what your platform
already knows:

```json POST /api/v1/envelopes theme={null}
{
  "template_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "recipients": [
    { "role": "Main Member", "name": "Thandi Mokoena", "email": "thandi@example.test" }
  ],
  "subjects": { "spouse": true, "dependant_1": true },
  "values": [
    { "subject": "main_member", "key": "first_name", "value": "Thandi" },
    { "subject": "main_member", "key": "id_number", "value": "8001015009087", "locked": true },
    { "subject": "spouse", "key": "first_name", "value": "Sipho" },
    { "subject": "dependant_1", "key": "first_name", "value": "Lerato" }
  ],
  "send": true
}
```

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.