Template Recipients

Template recipients define the roles in the signing workflow — who needs to sign, in what order, and whether their assignment is locked or open for override at send time.

---

Properties

Property	Type	Description
id	string	Unique identifier for the recipient role.
identifier	string	A stable slug used to reference this role when jumpstarting an envelope (e.g. "counterparty").
roleName	string	Human-readable label shown in the UI (e.g. "Counterparty").
type	string	Signing role type. Same as envelope recipients.
order	number	Signing order. Same ordering rules as envelope recipients.
required	boolean	If true, all fields assigned to this recipient must be completed before finalization.
fixed	boolean	If true, the assigned person cannot be overridden at jumpstart time. See below.
color	string	Display color used to identify this recipient's fields in the signing UI.
hostedById	string	For in_person_signer roles — the id of the host recipient.
delegatedById	string	For delegator roles — the id of the delegating recipient.

Pre-assigned persons

A template recipient can have a person pre-assigned through any of the following:

Field	Description
user	An internal Inspakt team user.
contact	A contact from the team's address book.
contactGroup	A contact group. All members of the group are assigned as agents.

---

Fixed vs. variable recipients

The fixed flag determines whether a recipient's assignment can be overridden when jumpstarting an envelope from the template.

Variable recipient (fixed: false, default)

The assignment is a suggestion — it can be replaced with a different person at jumpstart time. If no override is provided, the pre-assigned person is used.

Fixed recipient (fixed: true)

The assignment is locked. The person defined on the template will always be used, regardless of what is passed in the jumpstart request. Fixed recipients are typically used for internal roles that are always the same person — such as a legal approver or a general manager.

Example

Template: "Standard NDA"
│
├── Recipient A: "General Manager" [fixed]
│   └── Assigned to: Ahmet Bişeyoğlu (contact)
│
└── Recipient B: "Counterparty" [variable]
    └── No pre-assignment

When jumpstarting from this template, only the Counterparty slot needs to be filled in. The General Manager slot is already locked to Ahmet Bişeyoğlu and cannot be changed via the API.

{
  "recipients": [
    {
      "identifier": "counterparty",
      "agents": [
        {
          "info": {
            "name": "Jane Smith",
            "email": "[email protected]"
          }
        }
      ]
    }
  ]
}

---

Adding recipients to a template

POST /api/v1/key/templates/{templateId}/recipients
Content-Type: application/json

{
  "recipient": {
    "roleName": "Counterparty",
    "identifier": "counterparty",
    "type": "signer",
    "order": 1,
    "required": true,
    "fixed": false
  }
}

Removing recipients from a template

DELETE /api/v1/key/templates/{templateId}/recipients/{recipientId}

Possible errors

Name	Cause
Template.NotFound	The template does not exist.
Recipient.NotFound	The recipient does not exist on this template.
Recipient.HostRecipientBound	Cannot remove — another recipient is hosted by this one.
Recipient.DelegatorRecipientBound	Cannot remove — another recipient delegates through this one.