TL;DR: Directories are tags you add to contact groups. The AllowedDirectories setting on a send or template request tells us which groups the sender may use. Our eSignature API page shows what else the API covers.
Your app sends a contract to “the finance team”, and any finance member can sign. Then a second customer joins your platform with its own finance team. Now two groups share a name, and a sender could pick the wrong one.
Directories solve that. This guide covers what they are, the rules we apply, and how to set them up. Read our guide to group signers in the BoldSign API for the basics of sending to a group.
What is a directory for group signers?
A directory is a short label on a contact group, such as Finance, Legal or a team ID. Group signer settings read these labels to decide which groups a sender can use.
Think of an office building where each badge opens certain floors. The badge is the directory, and the floor is the set of documents a group may sign. A group without the right badge stays out.
A group signer is one signer slot that points at a whole contact group. A member of that group can then complete the signing step.
Why do contact groups need a directory?
Every contact group used as a group signer must have at least one directory. Add one to an older group before you put its GroupId in a send or template request.
The rule makes every group signer a deliberate choice. A group you created years ago for another purpose stays out of signing until you tag it.
How many directories can a contact group have?
Each contact group can hold up to 5 directories. Each directory value can be up to 40 characters long, according to our directories reference.
Five tags are usually enough to place one group in a department, a region and a tenant at once. Keep each value short and stable over time.
How do AllowedDirectories decide which groups can sign?
You set GroupSignerSettings.AllowedDirectories when you send a document or create or edit a template. Only contact groups in at least one allowed directory can act as group signers on that request.
Group signing needs two settings together:
- Set the recipient’s SignType to Group and give the GroupId.
- Set GroupSignerSettings.Enabled to true.
- Add AllowedDirectories, such as Finance and Legal, to limit the choice.
Groups outside those directories stay hidden from the sender. Senders can use only the contact groups their allowed directories cover.
What changes in embedded sending?
Embedded screens show only the contact groups that match AllowedDirectories. Senders search and pick from that filtered list.
An empty match shows the message “no records found”.
That filter does the work your own code would otherwise do. Your app passes the allowed directories, and the embedded screen hides every other group. Our guide to embedded signing for in-app contract signing explains the wider embedded flow.
How should you name directories in a multi-tenant app?
Use a stable unique value, such as a universally unique identifier (UUID) v4 for each team or tenant. Plain names such as Legal can repeat across customers and widen access by accident.
A UUID v4 looks like this: 550e8400-e29b-41d4-a716-446655440000. Map each directory to a team, department or business unit. Avoid per-user or temporary names, since a directory works as an access boundary.
How do you assign directories to contact groups?
You add directories when you create or update a contact group through our API. You can build the group and its members in the web app, but directories need an API call.
These Contact Groups API endpoints handle the work:
| Task | Method | Endpoint |
|---|---|---|
| Create a contact group with directories | POST | /v1/contactGroups/create |
| Add directories to an existing group | PUT | /v1/contactGroups/update |
| List the contact groups your account can use | GET | /v1/contactGroups/list |
| Delete a contact group by its ID | DELETE | /v1/contactGroups/delete |
| Get one contact group’s details by its ID | GET | /v1/contactGroups/get |
Where do directory rules help most?
Directory rules suit any process where a team, not one person, holds the right to sign. Here are common ways to map them:
- Department approvals: tag each department’s group, then allow only that department on its requests.
- HR policy sign-offs: allow the HR directory so other teams’ groups stay out of the list.
- Procurement and vendor contracts: route approvals only to procurement or compliance groups.
- Regional branches: give each region its own directory so one branch cannot pick another.
- Multi-tenant SaaS apps: give each tenant a UUID directory to keep groups apart.
What can go wrong with directory rules?
Most problems come from a mismatch between a group’s directories and the request. Check these first when a group fails to appear:
- The group’s directory is missing from AllowedDirectories on the request.
- Group signers are switched off, or no group sits in the allowed directories.
- The GroupId is wrong, or the sender has no access to that group.
Which BoldSign plan do you need, and what does it cost?
Live API calls, including group signers and embedded signing, need our Enterprise API plan. It starts at $30 a month with 40 envelopes, and each extra envelope costs $0.75.
Prices are in USD. You can build and test the whole flow first in a free API sandbox account, on any plan. The pricing page lists every plan and limit.
How do you start using directories with group signers?
Tag one contact group, send a test document with AllowedDirectories, and check that only the right group appears. These links help you take that first step:
- Create a free API sandbox account to test directories.
- Book a personalized demo to walk through your group setup.
- Ask our team on the support portal or read the send document reference.
Frequently asked questions
What is a directory in BoldSign group signing?
A directory is a tag you add to a contact group, such as Finance or a team ID. Group signer settings read these tags to decide which groups a sender may pick.
What happens if I use a GroupId without a directory?
You need to add one first. A contact group must carry at least one directory before you can use its GroupId in a send or template request.
Can I manage directories in the BoldSign web app?
Not at the moment. You can create a contact group and its members in the web app, but you add and change directories through the Contact Groups API only.
How many directories can a contact group have?
Each contact group can hold up to 5 directories. Each directory value can be up to 40 characters long.
Do individual signers need a directory?
No. Directories apply only to contact groups that you use as group signers. A signer you add by name and email works as usual.
Why use a UUID as a directory name in a multi-tenant app?
A universally unique identifier (UUID) stays unique across tenants. Plain names such as Legal can repeat across customers, and a repeated name can widen who sees a group.
Do directories change what users see in embedded sending?
Yes. The embedded screen lists only contact groups whose directories match AllowedDirectories. The search comes back empty when no group matches.
Which BoldSign plan do I need for group signers in a live app?
Live API calls need the Enterprise API plan, from $30 a month with 40 envelopes. You can build and test group signers first in a free API sandbox account.