---
title: "Share document group"
method: POST
path: "/v2/document-groups/{document_group_id}/roles"
---

# Share document group

`POST /v2/document-groups/{document_group_id}/roles`

## Request

- Base URL: `https://api.signnow.com`
- URL: `https://api.signnow.com/v2/document-groups/{document_group_id}/roles`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/signnow/apis/signnow-api/docs/v2/document-groups/:document_group_id/roles/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint allows API users to share a document group with a user by email, assigning them a specified role. If the user does not have an account, one is created automatically.

**Notes**

* **Viewer** - can view, download, and make copies of documents in a document group; **sender** - can view, download, make copies, invite to sign, and manage document invites.
* Only the owner of the document group can share it.
* A document group can be shared only once with the same user. Attempting to share again (even with a different role) returns an error.
* The user receives an email notification about the shared document group, including a preview link.
* If the user does not exist in the system, a new account is created automatically.
* If the document group was created from a document group template (DGT) that is already shared with the target user (as owner or sender), the sharing is rejected with a conflict error.

## Request body

- object
  - `role` string, required: Role to assign. Allowed values: `viewer`, `sender`.
  - `email` string, required: Email address of the user to share with.
  - `message` string: Custom message to include in the notification email.

## Response `200`

Document group successfully shared.

- object
  - `id` string: Unique identifier of the user.
  - `role` string: User's role in the document group (e.g., `viewer`, `sender`).
  - `email` string: Email address of the user.

## Other responses

- `400`: Bad request. Possible errors: * Document group not found. * You can't share document to yourself. * Entity can only be shared once. * Email validation errors. * Role validation errors. * Message validation errors.
- `403`: Forbidden. You don't have access to the document group.
- `404`: Incorrect document group ID format (not a 40-character hex string).
- `409`: Conflict. The document group is already shared with the user.

---

[API](https://skmtc.dev/signnow/apis/signnow-api.md) - [All operations](https://skmtc.dev/signnow/apis/signnow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signnow/apis/signnow-api/revisions/1c9c30a6142b?raw)