Recipient Groups
Learn how to add a pool of possible Signers or Approvers, so that the first one available signs or approves in their own name.
What is a Recipient Group?
You can use Recipient Groups to add a pool of possible Signers or Approvers in your Signature Requests. The first member who acts signs (or approves) in their own name, and only their name appears on the signed Documents and the Audit Trail. The other members no longer need to act.
A Recipient Group is not a new resource. It uses the existing Signer and Approver endpoints, with identity_pool instead of info. The group has one ID, used like any Signer ID.
Recipient Groups are available on Pro and Scale plans, and during the Trial. In Sandbox, they are available on all plans, with the Pro plan limits.
Create a Recipient Group
- Endpoint: Create a new Signer (
POST /signature_requests/{signatureRequestId}/signers)
Send identity_pool instead of info. The list must contain at least 2 members.
{
"identity_pool": [
{ "first_name": "Marie", "last_name": "Martin", "email": "[email protected]", "phone_number": "+33612345678", "locale": "fr" },
{ "first_name": "Paul", "last_name": "Durand", "email": "[email protected]", "phone_number": "+33698765432", "locale": "fr" }
],
"signature_level": "electronic_signature",
"signature_authentication_mode": "otp_sms"
}Use the same parameters as a single Signer (or Approver). The only difference: replace info with identity_pool, which is simply an array of info objects (at least 2). All other parameters apply to the whole group. Only the Simple Electronic Signature (electronic_signature) is available.
You can also:
- create an Approver group with the same body, using Create a new Approver,
- fill a Template placeholder with a group, by sending
identity_poolinstead ofinfointemplate_placeholders.signers. See Use Templates to create Signature Requests.
Follow a Recipient Group
When you get the Signer:
- Before a member signs:
infoisnullandidentity_poollists the members. - After a member signs:
infocontains the member who signed,statusissigned, andidentity_poolis kept.
Each member in identity_pool has their own signature_link (or approval_link for Approvers). With delivery_mode set to none, use these links to share the request yourself.
The signer.done (or approver.approved) webhook is sent once, with the group ID and the member who signed in info. No event is sent for the members who did not sign.
Rules to know
- One member at a time can be in the signing flow. After 10 minutes of inactivity, another member can start.
- If a member declines (or rejects), the whole Signature Request is declined (or rejected).
- Only the member who signed can access the signed Documents and the Audit Trail.
- A group consumes one signature, whatever the number of members.
- Group members count in the Signer and Approver limits of the Signature Request.
- You cannot sign or send an OTP for a Signer group with the API (Sign a Signature Request, Send a One-Time Password). The members sign from the Signature App or the Signature Portal.
| Plan | Recipient Groups per Signature Request |
|---|---|
| Trial | 2 |
| Pro | 2 |
| Scale | Unlimited, within the limits of 100 Signers and 10 Approvers per Signature Request |
Manage a Recipient Group
- Update the members: Update a Signer with a new
identity_pool. The list is fully replaced. You cannot update a group once a member has acted. - Delete the group: Delete a Signer.
- Send a reminder: Send manual reminder to a Signer. It is sent to all the members of the group until one of them acts.
Recipient Group or group_with_id?
group_with_id?group_with_id puts several recipients in the same step, and all of them must act. With a Recipient Group, only one member acts.
→ Read the guide: Configure recipient ordering
Related links
Updated 13 days ago

