# Group Signing

This guide explains how to configure group signing using the NSE API v1. Group signing controls how many recipients within a stage must complete their task before the envelope advances. There are two variants:

- **Group signing x out of x** — every recipient in the stage must sign (also called parallel signing).
- **Group signing x out of y** — only a subset needs to sign (e.g., 2 out of 5).


The rest of the envelope workflow — creating the envelope, uploading documents, adding recipients, placing fields, and sending — follows the same steps described in the [Basic Envelope Workflow](/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/03-developer-documentation/01-api-reference/basic-envelope-workflow) guide. This guide focuses on the one field that changes behavior: `requiredRecipientCompletions`.

## How It Works

When you create a stage, `requiredRecipientCompletions` defines how many recipients must complete before the stage closes and the envelope advances. All recipients in the stage receive their invitation at the same time.

| Variant | `requiredRecipientCompletions` | Effect |
|  --- | --- | --- |
| x out of x | Equal to total recipients | Every recipient must sign |
| x out of y | Less than total recipients | First x to sign close the stage; the rest can no longer act |


## Group Signing x out of x

All 3 recipients must sign before the envelope advances.

```
Stage: requiredRecipientCompletions = 3  (total recipients = 3)
  ├── Alice  →  must sign
  ├── Bob    →  must sign
  └── Carol  →  must sign
```

**Create the stage:**

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages
```

```json
{
  "name": "Board Members",
  "requiredRecipientCompletions": 3,
  "type": "signer"
}
```

**Add recipients** — call this endpoint once per recipient, saving each returned `id`:

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients
```

```json
{
 "givenName": "Alice",
 "surname": "Smith",
 "email": "alice.smith@example.com",
 "notificationChannels":
 [
  "email"
 ]
}
```

Repeat for Bob and Carol. Assign a signature field to each recipient via the tasks endpoint, then send. The envelope status stays `inProgress` until all 3 have signed.

## Group Signing x out of y

Only 2 of the 5 recipients need to sign. As soon as the second signature is collected, the stage closes and the remaining 3 recipients can no longer act.

```
Stage: requiredRecipientCompletions = 2  (total recipients = 5)
  ├── Alice  →  signs ✓
  ├── Bob    →  signs ✓  ← threshold reached, stage closes
  ├── Carol  →  no longer required
  ├── David  →  no longer required
  └── Eva    →  no longer required
```

**Create the stage:**

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages
```

```json
{
  "name": "Investment Committee",
  "requiredRecipientCompletions": 2,
  "type": "signer"
}
```

**Add recipients** — call this endpoint once per recipient, saving each returned `id`:

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients
```

```json
{ 
 "givenName": "Alice",
 "surname": "Smith",
 "email": "alice.smith@example.com",
 "notificationChannels": 
  [
   "email"
  ]
}
```

Repeat for Bob, Carol, David, and Eva — 5 calls in total. Every recipient needs a signature field assigned via the tasks endpoint, even though only 2 completions are required, so that any of them can be among the first to sign. Then send the envelope as usual.

## Key Rules

- `requiredRecipientCompletions` must be greater than `0` and no greater than the total number of recipients in the stage.
- Setting it equal to the total recipient count means everyone must sign (x out of x).
- Setting it lower means only the first x to sign are required (x out of y).