- A recipient names its role by name, never by position —
{ "role": "Witness" }. An ordinal breaks silently the first time somebody reorders a template, and a name the template does not declare is refused asrecipient_role_unknown, which says which name it was. - A role can be renamed and reordered in the template’s editor, in the dashboard, where
Who signs asks its roles either in order or all at the same time. Steps set another
way, such as with
role_steps, are shown there as a custom order and kept until somebody picks one of the two. A rename changes the name a request must use from then on; envelopes already made from the template, drafts included, keep the name they were made with. Read the names a template has now fromGET /api/v1/templates/{templateId}. - At least one role and at most 20. The editor has 6 role colours and repeats them when a template has more roles than that, so two roles can share a colour; a role is told apart by its name.
- ⚠️ The order is load-bearing. It is a role’s position in the recipient list and its colour in the editor. When each role is asked is its step, below.
- A role routed
ccis never asked to fill anything in. Detected fields skip past one. It is sent the finished document only when we deliver it —completion_deliveryofvumasignonPOST /api/v1/envelopes. Underintegrator, the default for an envelope sent with an API key, we send nobody anything at completion, accincluded. - A role is a
partyto the document or awitnessto a signature: itskind, read back on each role fromGET /api/v1/templates/{templateId}and set withrole_kindsonPOST /api/v1/templates. In the dashboard, Who signs sets it with Witnesses, and a role marked a witness can be made a party again; that changes only envelopes made afterwards. Over the API, a recipient takes the kind of the role it fills. A witness can be pre-signed only under the conditions in Standing authorisations. - A role is a recipient slot: whoever fills it signs, approves or receives a copy, as its routing says. The people a document is about — a main member, a spouse, a dependant — are subjects, a separate record from a recipient, and a field says which of them it is about. The two records can be the same person: a main member is the application’s subject and also the recipient who signs it. A spouse who is only described needs no role.
- One person may hold more than one role, so a recipient has no natural key. Address one by the
idthat comes back when the envelope is created — not by role name, and not by email. - Who fills a role can still change after send: the sender can correct a recipient and a recipient
can hand the document to somebody else. Either retires the recipient and adds a new one, with a
new
id. See Changing an envelope after it is sent. - A draft prepared in the dashboard can hold a person who is named later: a row with a role and
nobody yet, read back with
nameandemailofnull. Such a draft cannot be sent while somebody who signs or approves is still unnamed — sent through the API, it is refused asrecipient_role_missing— and a copy with no address is left off when it is sent. A request to the API cannot leave a recipient unnamed. - A recipient can be asked to enter a code emailed to them before the document opens, with
verification_methodon the recipient. It is chosen per recipient in the request, never on the template, and whoever replaces the recipient is asked for the same. See Signer verification.
Steps: who is asked when
Every recipient is in a step, a whole number. Everyone in the lowest step that still has something to do is asked together; the next step opens when that one is finished. Recipients who share a step are asked at the same time, and step numbers need not be consecutive. Acc is never
waited for.
A template’s roles carry steps, read back as step on each role from
GET /api/v1/templates/{templateId} and set with role_steps on
POST /api/v1/templates, or with signing_mode there instead (not both).
With neither, every role is in step 1. When Who signs in the dashboard asks everyone all at
the same time, witnesses are asked once the others have finished.
On a request that creates an envelope, give step on every recipient or on none. Without
it, the order of the recipients array decides, in one of two ways, and never by the template’s
own steps: a request that worked one way before steps existed still does, even after somebody edits
the template’s steps. To send in a template’s steps, read them and pass them.
Roles that can be left out
A template role can be optional: a lease’s surety, a loan’s co-applicant, a second witness. In the dashboard, open the role’s options in Who signs and tick Optional: can be left out of an envelope. Every role is required until somebody marks it optional, or Set up this form proposes it because the form marks that role’s signature “if applicable” or “optional”. When you send an envelope from that template, an optional role can be left empty, or emptied with Not on this envelope. When it is sent:- the role’s boxes are removed from the envelope, so nothing is shown, asked for, stamped or sealed in them;
- the role takes no step, so nobody waits for it;
- the envelope’s history records that the role was left out, and the sealed certificate lists it as not on this envelope.
Leaving a role out through the API
Each role onGET /api/v1/templates/{templateId} carries presence:
required or optional. Set it with role_presences on
POST /api/v1/templates, one entry per role, or with role_presence
on a person decision. To leave an optional role out of an envelope, leave its recipient out of
recipients. A required role with fields still has to be given somebody, or the request is refused
recipient_role_missing.
A value for a field only an omitted role holds would land nowhere, so it is refused
value_for_left_out_role and nothing is created. A value whose address is also on a role
that stays is written to that role’s fields. Once the envelope is sent, roles_left_out on the
envelope lists the roles it was sent without that held fields.
In a bulk send, leave both of an optional role’s cells blank to leave it out on that row.
Which documents a recipient sees
An envelope can hold more than one document: a template of several, a one-off of several, or a template with attachments. Every recipient is shown every document, with one exception: an envelope created withattachments on
POST /api/v1/envelopes. On such an envelope each recipient is
shown the documents that concern their role, when they sign and in the finished copies they are
sent. A recipient sees a document when any of these holds:
- their role has a field on it;
- nobody has a field on it, such as an annexure with no tags;
- their role has no field anywhere on the envelope, such as a
ccor an approver with nothing to fill in. Such a recipient sees every document.
attachments. Every other envelope, whether sent from
the dashboard, as a one-off, from a template alone or in a batch, shows every recipient every
document, so an employee asked to acknowledge a contract is shown the contract. Which way an
envelope works is fixed when it is sent.
On an envelope created with attachments:
- The sender and the API see every document. The dashboard shows the sender the whole envelope,
and
GET /api/v1/envelopes/{envelopeId}/documentsanswers with every document whichever recipient it concerns. - The completion email carries only that recipient’s documents. When Vumasign sends the finished
documents (
completion_deliveryofvumasign), each recipient’s email carries the sealed copies of the documents they were shown. A copy sent to the sender carries every document. - Each certificate of completion still lists every recipient on the envelope, including those who were not shown that document.