> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Share request with principals

POST https://api-d.docusign.com/v1/accounts/{accountId}/requests/{requestId}/shares/actions/add
Content-Type: application/json

Grants the specified users or groups access to the request at the given role. Granting a role a principal already holds has no effect.

Reference: https://developers.docusign.com/docs/agreement-desk-api/reference/agreementdesk/requestshares/addrequestshares

## Authentication

- `Authorization` header (bearer token, required) — Docusign OAuth 2.0 access token

## Servers

- `https://api-d.docusign.com` (Demo, default)
- `https://api.docusign.com` (Production)

## Request

### Path parameters

- `accountId` (string, required) — The ID of the account that owns the request statuses.
- `requestId` (string, required) — The ID of the request (Agreement Desk ticket) the document belongs to.

### Body (application/json)

This endpoint expects an AddSharesRequest.

- `principals` (list of Principal, required) — The principals to grant access to, each with the role to grant.
- `notify` (boolean, optional, default: false) — Whether to send notification emails to the affected principals.

## Response

### 200

The principals were granted access to the request.

## Errors

### 400 Bad Request Error

The request was malformed.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

### 401 Unauthorized Error

The request was not authenticated.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

### 403 Forbidden Error

The caller is not permitted to modify sharing on this request.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

### 404 Not Found Error

The specified request was not found.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

## Types

### Principal

A user or group that has been granted access to a request, and the role it holds.

- `id` (string, required) — The unique identifier of the principal (user or group).
- `role` (enum, required) — The level of access a principal holds on a request.
  - Allowed values: `VIEW`, `EDIT`, `MANAGE`
- `type` (enum, required) — The kind of principal an access grant applies to.
  - Allowed values: `user`, `group`

### ValidationError

A single field-level or parameter-level validation error.

- `code` (string, required) — A machine-readable error code identifying the specific validation failure.
- `message` (string, required) — A human-readable description of the validation error.
- `target` (string, optional) — The name of the field, parameter, or path segment that caused the error.

## Examples

**Request**

```json
{
  "principals": [
    {
      "id": "bbbb2222-cccc-4ddd-8eee-ffff33334444",
      "role": "VIEW",
      "type": "user"
    }
  ],
  "notify": false
}
```

**Response**

```json
{}
```