Creates a new workspace | Docusign

curl -X POST https://api-d.docusign.com/v1/accounts/accountId/workspaces \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "New Workspace",
  "brand_id": "21d17b0c-59bc-4879-9643-92d68bd9f8f6",
  "envelope_ids": null,
  "upload_requests": [
    {
      "name": "Upload Purchase Agreement",
      "description": "Please upload the fully executed purchase agreement.",
      "assignments": [
        {
          "first_name": "Alex",
          "last_name": "Johnson",
          "email": "alex.johnson@example.com"
        }
      ],
      "due_date": "2025-09-08T12:00:00Z",
      "status": "draft"
    }
  ],
  "batch_send": null
}'

{
  "workspace_id": "113e81b7-706e-4cab-9257-73b06325266e",
  "name": "New Workspace",
  "created_date": "2025-09-01T12:00:00Z",
  "created_by_user_id": "211e2d22-f070-4c8d-b6a7-ecb14ceb81b4",
  "workspace_owner_ids": [
    "211e2d22-f070-4c8d-b6a7-ecb14ceb81b4"
  ],
  "errors": [],
  "has_errors": false
}

Creates a new workspace that can include draft or in-progress envelopes, upload requests, and documents. A workspace is a collaborative hub in the Docusign platform where teams organize and track related agreements and supporting documents, while recipients get a clearer, consolidated place to complete their tasks.

With this operation, you can:

Create a branded workspace that serves as the central place for your team, client, project, or transaction.
Link existing envelopes (created via the eSignature API) or add in-flight ones so they are tracked together under a single workspace.
Create upload requests (for example, “Proof of Identity”) and assign them to specific recipients so you can collect documents in one organized hub.
Trigger a single batch send for all workspace tasks, using smart notifications so participants are informed across envelopes and upload requests without being over-notified.

Workspaces orchestration over envelopes and tasks Workspaces acts as an orchestration layer on top of the eSign API. You create envelopes with eSign, and Workspaces builds on them to group, send, and coordinate envelopes, upload requests, and participants in one place.

Light-lift integration: Create envelopes with status: “created” via the eSign API, then call createWorkspace with their IDs (and any upload requests). Workspaces imports them into one container.
Centralized sending: Workspaces batch-sends all associated envelopes and upload requests, updating their status to sent so you don’t have to send each envelope or task individually.
Participant orchestration: Invite internal team members into the workspace so they can see all envelopes and upload requests in one place, help manage tasks, and collaborate on client work.
Smart notifications: Workspace notifications replace most envelope-level emails, keeping inboxes clean while still alerting participants when new tasks are added after they’ve viewed the portal.
Single portal entry: Recipients receive one invitation into a secure, branded workspace view where they can review, sign, and upload everything in a single session.

The recommended way to use createWorkspace is the all-in-one pattern. In a single call, you create the workspace, import any draft envelopes you already built with the eSign API, attach upload requests, and trigger a batch send. This keeps your existing eSign integration mostly unchanged. You still create envelopes with status: “created”, and Workspaces handles grouping, sending, and participant coordination for everything in one place.

Required authentication scopes: dtr.rooms.write

Authentication

AuthorizationBearer

JWT Bearer token from Docusign authorization server

Path parameters

accountIdstringRequiredformat: "uuid"

The ID of the account

Request

The details of the workspace to be created including the name, optional envelope IDs to import, optional upload requests, and optional batch send flag

namestring or nullRequired

Required. The display name of the workspace.

brand_idstring or nullOptionalformat: "uuid"

Optional. A GUID value that identifies a brand to apply to the workspace. For more information, see Branding

envelope_idslist of strings or nullOptional

Optional. List of envelope IDs (created via the eSignature API) to import into the workspace. These envelopes will be grouped and tracked together under a single workspace.

upload_requestslist of objects or nullOptional

Optional. List of upload request objects that define tasks for collecting documents from recipients. For example, "Proof of Identity" or other required documents.

batch_sendboolean or nullOptional

Optional. When true, Workspaces batch-sends all eligible envelopes and upload requests after creation. When omitted or false, items remain in their current status until you send them later. Centralized sending ensures all associated envelopes and upload requests are sent together without needing to send each individually.

Response

Workspace successfully created

workspace_idstringOptionalformat: "uuid"

The ID of the workspace

namestring or nullOptional

The name of the workspace

created_datedatetime or nullOptional

The date the workspace was created

created_by_user_idstring or nullOptionalformat: "uuid"

The ID of the user who created the workspace

workspace_owner_idslist of strings or nullOptional

The list of user IDs of the workspace owners

errorslist of objects or nullOptional

The list of partial errors encountered while importing envelopes or creating upload requests

has_errorsbooleanOptionalRead-only

Errors

400

Bad Request Error

401

Unauthorized Error

500

Internal Server Error