How to add a document to Workspace

This topic demonstrates how to upload a document to a workspace using the Workspaces API.

Required data

Running the code in this how-to requires this data:

Step 1. Obtain your OAuth token

To make the API call shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

Wondering which grant type suits your integration? See Authenticate for guidance on your options to get an OAuth token.

Workspaces OAuth access tokens are the same ones used for our eSignature REST API, although you must request the signature scope and one or more Workspaces scopes to call the Workspaces API.

Step 2. Construct your API headers

After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for {ACCESS_TOKEN}.

declare -a Headers=(
    --header "Authorization: Bearer ${ACCESS_TOKEN}"
    --header "Accept: application/json"
)

Step 3. Construct the request body for a workspace envelope draft

Next, construct a request body for a local file path and a display name for the uploaded document. Validate that the file exists before continuing.

while true; do
    echo ""
    echo "Enter the PDF file name (e.g. World_Wide_Corp_Web_Form.pdf) from the ${DEMO_DOCS_PATH} folder:"
    echo ""
    read file_name
    file_path="$DEMO_DOCS_PATH/$file_name"
    if [[ "$file_name" != *.pdf ]]; then
        echo ""
        echo "The file must be a PDF (must end with .pdf). Please try again."
        continue
    fi
    if [ ! -f "$file_path" ]; then
        echo ""
        echo "File not found in demo_documents folder."
        continue
    fi
    break
done
# Enter the document name for the workspace
echo ""
echo "Enter the name for the document in the workspace (must end with .pdf):"
echo ""
while true; do
  read doc_name
  doc_name=$(echo "$doc_name" | xargs)
  if [[ "$doc_name" =~ \.pdf$ ]]; then
    break
  else
    echo ""
    echo "Invalid name. The document name must end with '.pdf' (e.g., example.pdf)."
    echo "Please try again:"
  fi
done

Step 4. Call the Workspaces API

Now that you have constructed your API headers and request body, make a POST request to the WorkspaceDocuments: addWorkspaceDocument endpoint and include the request body to add a workspace document. Here’s how you make the call, but make sure to substitute your API account ID for {API_ACCOUNT_ID}, your workspaces base path for {WORKSPACES_BASE_PATH}, and the desired workspace ID for {WORKSPACE_ID}.

Status=$(curl -s -w "%{http_code}" -o "${response}" \
    --request POST "${base_path}/accounts/${account_id}/workspaces/${workspace_id}/documents" \
    "${Headers[@]}" \
    -F "file=@${file_path};filename=${doc_name}" \
)

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown.

{
 "document_id": "12345678-1234-1234-1234-abcdef123456",
 "name": "My Uploaded Document.pdf",
 "owner_id": "09876543-4321-4321-4321-fedcba654321",
 "size": 102400,
 "created_date": "2025-05-30T18:00:00Z",
 "last_updated_date": "2025-05-30T18:10:00Z"
}

Next steps

• Run this code example from our Quickstart or launcher projects: Bash, or PowerShell.
• Learn How to send an envelope with recipient info.
• Review how to Go-Live with your integration.