Envelope Recipients

A recipient defines a role in the signing workflow — not a specific person. The actual person is assigned through an Agent. This separation allows you to define the signing structure once and assign different people each time.

---

Properties

Property	Type	Description
id	string	Unique identifier for the recipient. Required when assigning fields.
identifier	string	A stable slug you define for this role (e.g. "counterparty"). Used to reference the recipient in field assignments and API calls.
roleName	string	Human-readable label shown in the UI (e.g. "Counterparty").
type	string	Signing role type. See below.
order	number	Signing order. Recipients with the same order sign in parallel; lower values sign first.
required	boolean	If true, all fields assigned to this recipient must be completed before the envelope can finalize.
color	string	Display color used to identify this recipient's fields in the signing UI.
hostedById	string	For in_person_signer recipients — the id of the host recipient who facilitates the session.
delegatedById	string	For delegator recipients — the id of the recipient who can delegate to them.
agents	array	The persons assigned to this role. See Agents.

Timestamps

Property	Description
activatedAt	When this recipient's signing turn began.
completedAt	When this recipient completed all required actions.
delegatedAt	When the signing role was delegated to another person.
removedAt	When this recipient was removed from the envelope.

---

Recipient types

Type	Description
signer	Receives a signing link and completes their fields remotely.
host	Facilitates an in-person signing session for one or more in_person_signer recipients. The host initiates the session and hands the device to each signer.
in_person_signer	Signs in person on the host's device. Must be linked to a host via hostedById.
delegator	Can transfer their signing responsibility to another person at signing time.
viewer	Receives a read-only copy of the finalized envelope. Does not sign.

---

Signing order

The order field controls the sequence in which recipients are activated:

• Recipients with lower order values are activated first.
• Recipients with the same order value are activated simultaneously (parallel signing).
• A recipient is not activated until all recipients with a lower order have completed their actions.

order: 0  →  Internal approver
order: 1  →  Counterparty A  ┐ (parallel)
order: 1  →  Counterparty B  ┘
order: 2  →  Legal reviewer

---

Adding and removing recipients

Recipients can be added or removed while the envelope is in draft status.

Add a recipient

POST /api/v1/key/envelopes/{envelopeId}/recipients
Content-Type: application/json

{
  "recipient": {
    "type": "signer",
    "identifier": "counterparty",
    "roleName": "Counterparty",
    "order": 0,
    "required": true,
    "agents": [
      {
        "info": {
          "name": "Jane Smith",
          "email": "[email protected]",
          "locale": "en-US"
        }
      }
    ]
  }
}

Remove a recipient

DELETE /api/v1/key/envelopes/{envelopeId}/recipients/{recipientId}

caution

Removing a recipient also removes all fields assigned to that recipient.