Skip to navigation
Workspaces API 101

Workspaces API concepts

View as Markdown

The following sections describe the objects and key terms used by Docusign Workspaces API.

Workspaces

Docusign Workspaces is a single, digital place to bring people, agreements, and information together.

It simplifies customer experience by providing end users with a consolidated view of all forms, documents, and tasks related to a particular agreement process. A workspace provides a central place to track and manage every detail, task, and agreement document. Workspaces enable you to streamline complex agreements that include multiple parties, documents, and stages.

Envelopes

An envelope is a container for a Docusign agreement. An envelope object contains:

  • One or more documents that will be sent for electronic signature
  • Information about the sender
  • Information about the recipients, including authentication requirements and the areas where they need to provide input
  • The content of the email notification that recipients receive
  • Status information that tracks delivery and signature progress

Envelopes are used to secure agreements in a workspace just as they are used generally through the eSignature API.

To use envelopes within a workspace, for the initial release of Workspaces API, you must create envelopes in a workspace using a Workspaces API call, then modify the envelope using the eSignature REST API. Full import functionality is planned to be added in a future release. See How to send an envelope with recipient info for a detailed walkthrough.

Note: SMS, WhatsApp, and fax delivery are not available for envelopes you send from Workspaces.

Users

Users are individuals who are invited to collaborate together in a workspace for an agreement. Users must be assigned a role as either a manage or participate user.

Roles and permission levels

A role defines a set of permissions that are applied to users in a workspace. Roles are defined as either internal or external: internal users are users on the same account as the person who created the workspace. All other users are external.

Users can have one of two permission levels:

  • Manage users: Manage users can view all documents in the workspace, view completed envelopes, add and share documents, and invite other collaborators. The Manage permission can only be assigned to internal users. To have this role, users must be on the same account as the person who created the workspace.
  • Participate users: Participate users can view and complete agreement steps assigned to them. All external users must be assigned this permission level, but you can also optionally assign it to internal users as well.

Within these permission level categories, you can assign users a specific role:

  • Workspaces owner: The creator of the workspace.
  • Internal invitee: An individual invited to the workspace who is a member of the same Docusign account as the Workspaces owner.
  • External invitee: An individual invited to the workspace who is not a member of the same Docusign account as the Workspaces owner.
  • Internal or external non-invitee: Individual who is not invited to a workspace but is associated with the tasks or documents within the workspace. For example, an individual that is assigned an upload request.

See Actions Permitted By Permission Level and Role for details and a full matrix of which actions are permitted for each role.

You can update a user’s role by calling the WorkspaceUsers: updateWorkspaceUser API endpoint.

Documents

A document contains the content for a recipient to review or sign. Docusign supports documents in a variety of file formats, including PDF, Word, and HTML. A document object also contains metadata such as the file extension, file name, and document ID.

Documents in the context of Workspaces API behave just like documents do for eSignature. Users with the appropriate permissions can add documents to a room and share them with other users.

Next steps