How do I ask for signatures in a specific order?
Set hasSigningOrder: true and give each signer a number.
Two signers who share a number sign as one group — the next number is not
told anything until every signer in the group before it is done:
"signers": {
"A": { "email": "reviewer@acme.example", "fullName": "First reviewer",
"order": 1, "fields": [ /* ... */ ] },
"B": { "email": "approver@acme.example", "fullName": "Final approver",
"order": 2, "fields": [ /* ... */ ] }
},
"settings": {
"documentId": "...", "subject": "...",
"hasSigningOrder": true
}
Want the two of them to sign in parallel instead, as a pair, before a third
person? Give both of them "order": 1 and the third person
"order": 2. Leaving hasSigningOrder at its default
false is the same idea as giving everyone the same number: no
order, everybody notified together — and in that case order must
not be set at all (it would never be honoured, so the request is refused
rather than silently ignored).
Does the whole group have to sign, or just one of them?
Each signer also takes a groupMode, and it means nothing on
its own — it describes the group a shared order forms,
so every signer sharing a number must agree on it (or leave it unset and let
somebody else in the group decide):
| Value | Means |
|---|---|
"AND" (default) | Everybody sharing this
order must sign before the next group is told anything —
the behaviour this product always had, and what you get by leaving
groupMode out. |
"OR" | The first signature in
the group is enough. Everybody else still pending in it is marked
"skipped" in the response, their link dies immediately, and
the next group is told right away. A skipped link opens a page that says
the link is no longer valid, and nothing can be done with it; a request
already in flight from that page is refused with
RECIPIENT_NOT_REQUIRED. |
The normal shape — two named approvers, either one will do — is two groups of one signer each, one per group:
"signers": {
"A": { "email": "finance-a@acme.example", "fullName": "Approver A",
"order": 1, "groupMode": "OR", "fields": [ /* ... */ ] },
"B": { "email": "finance-b@acme.example", "fullName": "Approver B",
"order": 1, "groupMode": "OR", "fields": [ /* ... */ ] }
},
"settings": { "hasSigningOrder": true }
Both share "order": 1 — one group — and both say
"OR": whichever of the two signs first satisfies the group, the
other's link dies, and there is no second group to wait on. Put the two
approvers on different order values instead (still one signer
each) and you have two sequential groups, not one OR'd pair — order is what
makes a group, groupMode only says how it behaves.
A cap on the shape, not only the total.
MAX_RECIPIENTS (20) already bounds every envelope, but an
ordered one is bounded two more ways at once: at most 5 distinct
order values (groups) and at most 4 signers
sharing any one of them. Both are the same 5×4 = 20 ceiling
seen from the shape rather than the total, and going over either answers
a plain 422 naming which limit and which value —
settings.hasSigningOrder being false skips both checks, since
there is no group to bound.
Full settings reference: Signing on its own.