Skip to main content
A template declares roles — “Employee”, “Witness” — and an envelope names the people who fill them. They are separate because their lifetimes are: the template is authored once and the people change every time it is sent.
  • 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 as recipient_role_unknown, which says which name it was.
  • At least one role and at most 6. The ceiling is a count of colours: the editor draws each role’s fields in its own, and there are 6 of them.
  • ⚠️ The order is load-bearing. It is a role’s position in the recipient list, its colour in the editor, and — when signing_mode is sequential — the order people are actually asked, each invitation going out only when the one before it is finished.
  • A role routed cc is never asked to fill anything in. Detected fields skip past one. It is sent the finished document only when we deliver it — completion_delivery of vumasign on POST /api/v1/envelopes. Under integrator, the default for an envelope sent with an API key, we send nobody anything at completion, a cc included.
  • One person may hold more than one role, so a recipient has no natural key. Address one by the id that comes back when the envelope is created — not by role name, and not by email.