> 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

# Adds a user to the workspace by email address

POST https://api-d.docusign.com/v1/accounts/{accountId}/workspaces/{workspaceId}/users
Content-Type: application/json

This operation manually adds an internal or external user to a specific workspace by email address. Users within the account are considered "Internal" and may be assigned any role. Users outside the account are considered "External" and may only be assigned the Participate role. This operation is not typically needed for adding external participants to a Workspace as they will be automatically added as tasks are assigned.

Available role IDs can be retrieved via the Assignable Roles operation on a workspace. If the `role_id` is not passed, the user is added with the Participate role.

[Required authentication scopes](/docs/workspaces-api/auth/): `dtr.rooms.write`

Reference: https://developers.docusign.com/docs/workspaces-api/reference/workspaces/workspaceusers/addworkspaceuser

## Authentication

- `Authorization` header (bearer token, required) — JWT Bearer token from Docusign authorization server

## Servers

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

## Request

### Path parameters

- `accountId` (string, required) — The ID of the account
- `workspaceId` (string, required) — The ID of the workspace

### Body (application/json)

This endpoint expects a WorkspaceUserForCreate.

- `email` (string, required) — The email address of the added user. May be an internal user to the account or an external user
- `first_name` (string, required) — The first name of the added user
- `last_name` (string, required) — The last name of the added user
- `role_id` (string, optional, nullable) — The optional Role ID to assign to the user. Defaults to the "Participate" role

## Response

### 201

The user was successfully added to the workspace

- `workspace_id` (string, optional) — The ID of the workspace
- `user_id` (string, optional) — The ID of the user
- `role_id` (string, optional) — The ID of the role assigned to the user
- `email` (string, optional, nullable) — The email of the user
- `first_name` (string, optional, nullable) — The first name of the user
- `last_name` (string, optional, nullable) — The last name of the user

## Errors

### 400 Bad Request Error

Bad request. See ErrorCode and Message for details

- `message` (string, optional, nullable) — A brief message describing the error condition
- `errorCode` (string, optional, nullable) — A standardized code that generalizes the specific error

### 401 Unauthorized Error

Not authorized to make this request

- `message` (string, optional, nullable) — A brief message describing the error condition
- `errorCode` (string, optional, nullable) — A standardized code that generalizes the specific error

### 500 Internal Server Error

Internal Server Error

- `message` (string, optional, nullable) — A brief message describing the error condition
- `errorCode` (string, optional, nullable) — A standardized code that generalizes the specific error

## Examples

**Request**

```json
{
  "email": "string",
  "first_name": "string",
  "last_name": "string"
}
```

**Response**

```json
{
  "workspace_id": "113e81b7-706e-4cab-9257-73b06325266e",
  "user_id": "3b2c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "role_id": "7f2a9e1c-5b8d-4f6a-a1c3-8e4b7d1a5c9f",
  "email": "jane.smith@example.com",
  "first_name": "Jane",
  "last_name": "Smith"
}
```