# Group Signers

Group Signers allow you to use a Contact Group as a signer when sending documents or creating templates via the BoldSign API. This is useful when a signature request should be completed by any one member of a defined group (for example, “AccountsPayable”, “LegalReview”, or “HR”).

When you configure a recipient as a Group Signer:

-   The recipient represents a _group_ (a single signer slot in the workflow).
-   A member from that group can complete the signing action.
-   Access to groups in embedded experiences can be restricted using **Directories** for safer, multi-team usage.

To manage contact groups, use the BoldSign web app or the Contact Groups APIs.
{% customlink href="/contactGroups/create-contactGroups/#create-contactgroup" text="Contact Groups API" /%}

## Prerequisites

Before sending a document or creating a template with a Group Signer:

1. Create the contact group and add members (via web app or Contact Groups API).
2. Get the group's identifier (`GroupId`) (from the web app or from the {% customlink href="/contactGroups/list-contactGroups/" text="List Contact Groups API" /%}).
3. Assign at least one **Directory** to the contact group (see {% customlink href="/group-signers/directories/" text="Directories" /%}). This is **required** to use Group Signers, and directories are managed **only via API**.

If you are using an existing contact group, make sure it has a directory assigned before you reference it in `Send Document` or `Create Template` requests.

## Configuration fields

### Recipient fields

-   **`SignType`**
    -   Set to `Group` to indicate that this recipient is a contact group.
-   **`GroupId`**
    -   The identifier of the contact group to use as the signer.

These fields are documented in the Documents/Templates request models. For example:

-   {% customlink href="/documents/send-document/" text="Send Document API" /%}
-   {% customlink href="/template/create-template/" text="Create Template API" /%}

### Group Signer settings

Add `GroupSignerSettings` in the request to control whether group signing is allowed and which groups are selectable:

-   **`Enabled`**
    -   When `true`, group signers are allowed for the request.
-   **`AllowedDirectories`**
    -   A list of directories used to filter which contact groups can be used.
    -   See {% customlink href="/group-signers/directories/" text="Directories" /%}.

This design makes Group Signers explicit: you must both (a) mark a recipient as a group and (b) allow group signers in settings.

## Embedded experience

When **group signer settings are enabled**, BoldSign embedded experiences can allow the sender to add group recipients. Senders can search for and select contact groups that match the allowed directories.

To protect data in multi-team organizations, the embedded UI will only show contact groups that match the configured `AllowedDirectories`. If no contact groups match, the embedded UI will show **no records found**.

## Minimal example

The exact request payload varies by endpoint (send document, create template, etc.), but the relevant fields typically look like this:

```json
{
    "groupSignerSettings": {
        "enabled": true,
        "allowedDirectories": ["Finance", "Legal", "8371b0a2-fd72-4651-9d2e-6f7828a51e2c"]
    },
    "signers": [
        {
            "signType": "Group",
            "groupId": "<CONTACT_GROUP_ID>"
        }
    ]
}
```

## Common issues

-   **Group is not visible/selectable**: The group's directory is not included in `AllowedDirectories`.
-   **No groups are available**: No contact groups exist in the allowed directories, or group signers are not enabled.
-   **Incorrect group identifier**: The `GroupId` is invalid or not accessible to the sender.

## Related topics

-   {% customlink href="/contactGroups/list-contactGroups/" text="List Contact Groups" /%}
-   {% customlink href="/group-signers/directories/" text="Directories" /%}