# Directories

Directories are tags (categories) that you assign to **Contact Groups**. They are used by Group Signer settings to:

-   Filter which contact groups are available for selection.
-   Prevent accidental exposure of contact groups across teams within the same organization.
-   Support safe, scalable usage of Group Signers in embedded and API-driven flows.

If you are new to Group Signers, start here: {% customlink href="/group-signers/introduction/" text="Group Signers" /%}.

## Requirement for Group Signers

To use a contact group as a Group Signer, the contact group must have **at least one directory** assigned.

-   This applies to both newly created and existing contact groups.
-   If an existing contact group has no directories, you must assign a directory before using its `GroupId` in `Send Document` / `Create Template` requests.

Directories are managed on contact groups **only via API**.

Use the Contact Groups APIs to create or update a contact group with its directory values:

-   {% customlink href="/contactGroups/create-contactGroups/#create-contactgroup" text="Create Contact Group" /%}
-   {% customlink href="/contactGroups/update-contactGroup/" text="Update Contact Group" /%}

## How directories are used

Directories are applied through `GroupSignerSettings.AllowedDirectories` when sending a document or creating/editing a template.

-   If `AllowedDirectories` is configured, only contact groups that belong to at least one allowed directory can be used as Group Signers.
-   If a contact group is not in an allowed directory, it will be restricted from use.

This is especially important for embedded experiences where users can search and select contact groups.

## Limitations

The following limitations apply when assigning directories to contact groups:

-   You can add a maximum of **5** directories to a contact group.
-   Each directory value can be up to **40 characters**.

## Recommended directory strategy

To keep administration and access control straightforward:

-   Use directories that map to teams, departments, or business units (for example: `Finance`, `Legal`, `HR`).
-   In multi-tenant setups, prefer **UUID v4** directory values to avoid name collisions (example: `550e8400-e29b-41d4-a716-446655440000`).
-   Keep names stable over time; avoid per-user or temporary naming.
-   Treat directories as an access control boundary for Group Signer selection.

## Multi-tenancy

Group Signers are designed with **strict sender isolation** to reduce cross-team access within an organization:

-   Senders can only use contact groups from directories that are allowed in their `GroupSignerSettings`.
-   Contact groups in disallowed directories are restricted from being used as signers.
-   This prevents accidental exposure of contact groups across teams.

To make isolation robust at scale, use a **stable unique identifier** as the directory value (for example, the sender's **team ID** or **organization unit ID** in UUID v4 form). This reduces the risk of two teams independently choosing the same human-readable directory name (such as `Legal`) and unintentionally broadening access when `AllowedDirectories` is applied.