---
title: "Share document"
url: "https://docs.signnow.com/docs/document/operations/share-document"
type: "endpoint"
section: "document"
slug: "document/operations/share-document"
method: "POST"
path: "/v2/shared-entities"
operation_id: "share-document"
authorization: "bearer"
---

# Share document

`POST /v2/shared-entities`

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.

## Authorization

bearer

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "entity_type",
          "entity_id",
          "email",
          "role"
        ],
        "properties": {
          "role": {
            "type": "string",
            "example": "viewer",
            "description": "Role to assign. Allowed values: `viewer`, `sender`."
          },
          "email": {
            "type": "string",
            "example": "user@email.com",
            "description": "Valid email address of the recipient."
          },
          "message": {
            "type": "string",
            "example": "Please review the document.",
            "description": "Custom message to include in the notification email."
          },
          "entity_id": {
            "type": "string",
            "example": "abc123def456abc123def456abc123def456abc1",
            "description": "Document unique ID."
          },
          "entity_type": {
            "type": "string",
            "example": "document",
            "description": "Type of the entity to share. Allowed value: `document`."
          }
        }
      },
      "description": "Non-empty array of share requests."
    }
  }
}
```

**Example** (`application/json`)

```json
{
  "data": [
    {
      "role": "viewer",
      "email": "user1@email.com",
      "message": "Please review the document.",
      "entity_id": "aaa111bbb222aaa111bbb222aaa111bbb222aaa1",
      "entity_type": "document"
    },
    {
      "role": "sender",
      "email": "user2@email.com",
      "message": "Sending this document for your attention.",
      "entity_id": "bbb222ccc333bbb222ccc333bbb222ccc333bbb2",
      "entity_type": "document"
    }
  ]
}
```

## Responses

### 200

Document successfully shared.

**Example** (`Example 1`)

```json
{
  "data": [
    {
      "id": "def456abc123def456abc123def456abc123def4",
      "email": "user1@email.com",
      "entities": [
        {
          "role": "viewer",
          "entity_id": "aaa111bbb222aaa111bbb222aaa111bbb222aaa1",
          "entity_type": "document"
        }
      ]
    },
    {
      "id": "bf567a8af1b544afa55b40c40063652891ffcd31",
      "email": "user2@email.com",
      "entities": [
        {
          "role": "sender",
          "entity_id": "bbb222ccc333bbb222ccc333bbb222ccc333bbb2",
          "entity_type": "document"
        }
      ]
    }
  ]
}
```

**Example** (`application/json`)

```json
{
  "data": [
    {
      "id": "def456abc123def456abc123def456abc123def4",
      "email": "user1@email.com",
      "entities": [
        {
          "role": "viewer",
          "entity_id": "aaa111bbb222aaa111bbb222aaa111bbb222aaa1",
          "entity_type": "document"
        }
      ]
    },
    {
      "id": "bf567a8af1b544afa55b40c40063652891ffcd31",
      "email": "user2@email.com",
      "entities": [
        {
          "role": "sender",
          "entity_id": "bbb222ccc333bbb222ccc333bbb222ccc333bbb2",
          "entity_type": "document"
        }
      ]
    }
  ]
}
```

### 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.

**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 12030002,
      "message": "Data should not be null, value: [null] given."
    }
  ]
}
```

**Example** (`Data is null`)

```json
{
  "errors": [
    {
      "code": 12030002,
      "message": "Data should not be null, value: [null] given."
    }
  ]
}
```

**Example** (`role is empty`)

```json
{
  "errors": [
    {
      "code": 12030013,
      "message": "Field role should not be empty."
    }
  ]
}
```

**Example** (`email is empty`)

```json
{
  "errors": [
    {
      "code": 12030010,
      "message": "Field email should not be empty."
    }
  ]
}
```

**Example** (`message is empty`)

```json
{
  "errors": [
    {
      "code": 12030021,
      "message": "Field message must not be empty."
    }
  ]
}
```

**Example** (`message too long`)

```json
{
  "errors": [
    {
      "code": 12030023,
      "message": "Field message should not exceed 10000 characters."
    }
  ]
}
```

**Example** (`message too short`)

```json
{
  "errors": [
    {
      "code": 12030023,
      "message": "Field message should be not less than 1 characters."
    }
  ]
}
```

**Example** (`Invalid role value`)

```json
{
  "errors": [
    {
      "code": 12030014,
      "message": "Field role value should be one of [\"viewer\", \"sender\"], value: [admin] given."
    }
  ]
}
```

**Example** (`email is not valid`)

```json
{
  "errors": [
    {
      "code": 12030011,
      "message": "Field email should be valid email."
    }
  ]
}
```

**Example** (`entity_id is empty`)

```json
{
  "errors": [
    {
      "code": 12030008,
      "message": "Field entity_id should not be empty."
    }
  ]
}
```

**Example** (`Data array is empty`)

```json
{
  "errors": [
    {
      "code": 12030024,
      "message": "The data field should not be an empty array."
    }
  ]
}
```

**Example** (`Data is not an array`)

```json
{
  "errors": [
    {
      "code": 12030001,
      "message": "The data field must be an array."
    }
  ]
}
```

**Example** (`entity_type is empty`)

```json
{
  "errors": [
    {
      "code": 12030005,
      "message": "Field entity_type should not be empty."
    }
  ]
}
```

**Example** (`role is not a string`)

```json
{
  "errors": [
    {
      "code": 12030012,
      "message": "Field role should be string, value: [1] given."
    }
  ]
}
```

**Example** (`email is not a string`)

```json
{
  "errors": [
    {
      "code": 12030009,
      "message": "Field email should be string, value: [1] given."
    }
  ]
}
```

**Example** (`Cannot share with owner`)

```json
{
  "errors": [
    {
      "code": 12030016,
      "message": "Cannot share entity with the same owner."
    }
  ]
}
```

**Example** (`message is not a string`)

```json
{
  "errors": [
    {
      "code": 12030022,
      "message": "Field message should be string, value: [...] given."
    }
  ]
}
```

**Example** (`Invalid entity_type value`)

```json
{
  "errors": [
    {
      "code": 12030006,
      "message": "Field entity_type value should be one of [\"document\"], value: [group] given."
    }
  ]
}
```

**Example** (`entity_id is not a string`)

```json
{
  "errors": [
    {
      "code": 12030007,
      "message": "Field entity_id should be string, value: [1] given."
    }
  ]
}
```

**Example** (`entity_type is not a string`)

```json
{
  "errors": [
    {
      "code": 12030004,
      "message": "Field entity_type should be string, value: [1] given."
    }
  ]
}
```

**Example** (`Duplicate email and entity_id`)

```json
{
  "errors": [
    {
      "code": 12030015,
      "message": "Duplicated fields email and entity_id."
    }
  ]
}
```

### 401

Incorrect or missing bearer token.

**Example** (`Example 1`)

```json
{
  "code": 1537,
  "error": "invalid_token"
}
```

**Example** (`Unauthorized`)

```json
{
  "code": 1537,
  "error": "invalid_token"
}
```

### 403

Forbidden. Possible errors:

* User is not the owner of the shared entity.
* Document already shared with target user.

**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 12030017,
      "message": "User is not owner of shared entity."
    }
  ]
}
```

**Example** (`User is not owner`)

```json
{
  "errors": [
    {
      "code": 12030017,
      "message": "User is not owner of shared entity."
    }
  ]
}
```

**Example** (`Parent entity already shared`)

```json
{
  "errors": [
    {
      "code": 12030020,
      "message": "Sharing entity conflict: parent entity already shared."
    }
  ]
}
```

### 409

The document is part of a group and cannot be shared separately.

**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 12030025,
      "message": "Sharing entity conflict: not allowed to share separately a document that is part of a group."
    }
  ]
}
```

**Example** (`Document is part of a group`)

```json
{
  "errors": [
    {
      "code": 12030025,
      "message": "Sharing entity conflict: not allowed to share separately a document that is part of a group."
    }
  ]
}
```

## Code Examples

> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.

### cURL

```bash
curl -X POST \
  "https://api.signnow.com/v2/shared-entities" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": [{"role": "viewer", "email": "user1@email.com", "message": "Please review the document.", "entity_id": "aaa111bbb222aaa111bbb222aaa111bbb222aaa1", "entity_type": "document"}, {"role": "sender", "email": "user2@email.com", "message": "Sending this document for your attention.", "entity_id": "bbb222ccc333bbb222ccc333bbb222ccc333bbb2", "entity_type": "document"}]}'
```

---
*Full reference: https://docs.signnow.com/docs/document/operations/share-document*