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

# Roles and recipients

> A template declares roles; an envelope names the people who fill them.

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`](/api-reference/create-envelope). 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.