---
title: "Share document"
method: POST
path: "/v2/shared-entities"
---

# Share document

`POST /v2/shared-entities`

## Request

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

This endpoint allows API users to share documents with one or more users. For each document-email pair, assign a `viewer` or `sender` role.

**Notes**

* **Viewer** - can view and download the document; **sender** - can view, download, invite to sign, and manage document invites.
* Only documents owned by the authenticated user may be shared.
* If the recipient already has access, their role is updated to the value sent in the request.
* The recipient receives an email notification with a link to the shared document.
* If the recipient does not exist in the system, a new account is created automatically.
* The document owner's email must not appear among the recipients.
* Documents belonging to a document group cannot be shared individually.
* Documents created from a template already shared with the target user are rejected with a conflict error.

**Request limits:** At most **100 distinct recipient emails** and **20 distinct documents** per request.

## Request body

- object
  - `data` object[], required: Non-empty array of share requests.
    - `role` string, required: Role to assign. Allowed values: `viewer`, `sender`.
    - `email` string, required: Valid email address of the recipient.
    - `message` string: Custom message to include in the notification email.
    - `entity_id` string, required: Document unique ID.
    - `entity_type` string, required: Type of the entity to share. Allowed value: `document`.

## Response `200`

Document successfully shared.

- object
  - `data` object[]: Users the documents were shared with.
    - `id` string: Unique identifier of the recipient user.
    - `email` string: Email address of the recipient.
    - `entities` object[]: Documents shared with the user.
      - `role` string: Role assigned to the user: `viewer` or `sender`.
      - `entity_id` string: ID of the document.
      - `entity_type` string: Type of the shared entity. Always `document`.

## Other responses

- `400`: Bad request. Possible errors: * Data is null. * Data is not an array. * Data array is empty. * `entity_type` is not a string or is empty. * `entity_type` value is not `document`. * `entity_id` is not a string or is empty. * `email` is not a string, is empty, or is not a valid email. * `role` is not a string, is empty, or is not `viewer` or `sender`. * Duplicate `email` and `entity_id` pair. * Cannot share entity with the same owner. * `message` field errors.
- `401`: Incorrect or missing bearer token.
- `403`: Forbidden. Possible errors: * User is not the owner of the shared entity. * Document already shared with target user.
- `409`: The document is part of a group and cannot be shared separately.

---

[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)