This guide explains how to control the order in which recipients sign an envelope — sequential vs parallel — and how mandatory and optional recipients affect the outcome when someone declines.
The isSignOrder flag on the envelope controls the signing mode:
| Mode | isSignOrder | Behaviour |
|---|---|---|
| Parallel | false | All recipients are notified simultaneously and can sign in any order |
| Sequential | true | Recipients are notified one at a time in the order they appear in the recipients array |
To have Jane sign before John, set isSignOrder: true and list Jane first in the recipients array. John receives his notification only after Jane completes her fields:
{
"recipients": [
{
"referenceSignerId": 1,
"name": "Jane Smith",
"email": "jane@example.com",
"role": "signer",
"mandatory": true
},
{
"referenceSignerId": 2,
"name": "John Doe",
"email": "john@example.com",
"role": "signer",
"mandatory": true
}
],
"envelope": {
"isSignOrder": true,
...
}
}The mandatory flag controls what happens when a recipient declines:
Mandatory (true) | Optional (false) | |
|---|---|---|
| Recipient declines | Entire envelope is declined — all other recipients are notified | Decline is recorded but envelope continues |
| Use when | Signature is legally required from this party | Signature is desirable but not blocking |
You can mix mandatory and optional recipients in the same envelope. In this example, Jane is mandatory but Alex is optional — if Alex declines, the envelope can still complete:
"recipients": [
{
"referenceSignerId": 1,
"name": "Jane Smith",
"email": "jane@example.com",
"role": "signer",
"mandatory": true
},
{
"referenceSignerId": 2,
"name": "Alex Brown",
"email": "alex@example.com",
"role": "signer",
"mandatory": false
}
]A recipient with role: "viewer" can read the document and leave comments but is not required to sign. Reviewers do not block envelope completion regardless of their mandatory setting. Use them for approval workflows where a stakeholder needs visibility without a signature obligation:
{
"referenceSignerId": 3,
"name": "Legal Team",
"email": "legal@example.com",
"role": "viewer",
"mandatory": false
}A recipient group allows you to define a signing role that any one member can fulfil — only one person from the group needs to sign for the group's action to be considered complete. This is useful when the specific signer isn't known in advance, or when any authorised representative from a team or department can sign on behalf of the group.
Groups are defined in a top-level signGroups array. Each group has a referenceSignGroupId, a role, and a mandatory flag. Recipients and fields are then linked to the group via referenceSignGroupId instead of the individual referenceSignerId:
{
"recipients": [
{
"referenceSignerId": 1,
"referenceSignGroupId": 1,
"name": "Jane Smith",
"email": "jane@example.com"
},
{
"referenceSignerId": 2,
"referenceSignGroupId": 1,
"name": "John Doe",
"email": "john@example.com"
}
],
"signGroups": [
{
"referenceSignGroupId": 1,
"role": "signer",
"mandatory": true
}
],
"fields": [
{
"type": "signature",
"name": "signature_group",
"referenceDocumentId": 1,
"referenceSignGroupId": "1",
"isRequired": true,
"page": 1,
"positionX": 100,
"positionY": 650,
"width": 200,
"height": 60
}
]
}In this example, Jane and John are both members of group 1. Whichever one signs first completes the group's requirement — the other is not notified or required to act.
When using recipient groups,
roleandmandatoryare defined on thesignGroupsentry, not on individual recipients. Individual recipients in a group carry onlyreferenceSignGroupId,name, and