Manage Shared Spaces

Create, update, retrieve, and delete Shared Spaces programmatically. Automate Shared Space creation, integrate with existing workflows, and manage access.

By embedding Shared Spaces into sales processes, you can drive adoption, improve buyer engagement, and enhance deal outcomes. Automation lets sellers focus on building relationships and closing deals faster, while delivering consistent, high-quality buyer experiences.

What you'll learn:

How to create Shared Spaces with or without templates
How to update, retrieve, and delete Shared Spaces
How to transfer ownership between users

TL;DR

Create a Shared Space? Use POST /shared-spaces with owner and title
Use a template? Include sharedSpaceTemplate.id in the request body
Transfer ownership? Use POST /shared-spaces/{id}/transfer-ownership

When to use the API

Automate Creation	Standardize Workflows	Integrate with Other Systems	Manage Access	Build Custom Workflows
Automatically create a Shared Space when a deal advances in your CRM.	Use templates for consistency across different scenarios.	Create or update Shared Spaces from other systems (CRM, CPQ, etc.).	Modify ownership and access when information changes in your CRM.	Create Shared Spaces for specific scenarios or ad hoc collaboration.

Auto-creation Notifications

Whenever the automatic creation of a new Shared Space is triggered, the designated owner receives a notification about it.

This notification includes the following information:

Subject - A new Shared Space has been created for you.
Body - You have a new automatically created Shared Space, [Shared Space Name]. As the assigned owner, you have full control to personalize and manage this Shared Space. This automation was configured by your Showpad administrator.
View Shared Space - A direct link to the new Shared Space.

Note

This notification can not be modified or customized.

Prerequisites

Plan: Ultimate | Advanced or Expert
Permissions: Administrator access to Showpad's Admin App
Authentication: Valid OAuth 2.0 access token (learn more)
Config: Shared Spaces enabled

Base Endpoint

The base endpoint for Shared Space management calls is:

https://{{subdomain}}.api.showpad.com/v4

Every API v4 request needs to be prefixed with the base endpoint.

CORS

These endpoints are designed for server-to-server integrations. Browsers block cross-origin requests to the API, so you cannot call them directly from client-side JavaScript.

Activity Timeline

Requests made using an API token associated with a user who is not a participant in the Shared Space (always the case when creating a Shared Space), activities in the Shared Space activity timeline will appear as one of the following:

An automation created the Shared Space
An automation transferred ownership to Sales User

The Shared Space object

When you retrieve or create a Shared Space, the API returns the following fields:

Field	Type	Description
`id`	string	Unique identifier for the Shared Space
`title`	string	Customer-facing name of the Shared Space
`publicUri`	string	URL-friendly identifier for the Shared Space
`publicUrl`	string	Full URL to access the Shared Space
`status`	string	Current state: `ACTIVE` or `ARCHIVED`
`isExternalDownloadAllowed`	boolean	Whether participants can download content
`isExternalInviteAllowed`	boolean	Whether participants can invite others
`isExternalUploadAllowed`	boolean	Whether participants can upload content
`createdAt`	string	ISO 8601 timestamp when the Shared Space was created
`lastActivityAt`	string	ISO 8601 timestamp of the last activity
`archivedAt`	string	ISO 8601 timestamp when archived (or `null`)
`description`	string	Descriptive text for the Shared Space
`owner.userId`	string	User ID of the Shared Space owner
`theme.id`	string	ID of the applied Sharing Theme
`sharedSpaceTemplate.id`	string	ID of the template used (or `null`)

Create and Update

Request Body

Your Create Shared Space and Update Shared Space requests should include the following fields:

Field	Type	Description	Required
`owner.userId`	string	The user ID of the Shared Space owner. The owner receives an email notification and access requests.	Yes
`title`	string	Customer-facing name for the Shared Space. Optional if using a template with a title.	Yes*
`publicUri`	string	Custom URL slug. Must be unique. Auto-generated if not provided. Cannot be changed after creation.	No
`description`	string	Descriptive text for the Shared Space.	No
`isExternalDownloadAllowed`	boolean	Allow participants to download content. Default: `true`	No
`isExternalInviteAllowed`	boolean	Allow participants to invite others. Default: `true`	No
`isExternalUploadAllowed`	boolean	Allow participants to upload documents. Requires Collaborate+ add-on.	No
`theme.id`	string	ID of a Sharing Theme. Uses Global Theme if not set.	No
`sharedSpaceTemplate.id`	string	ID of a Shared Space Template. Requires feature activation.	No

Create Shared Space

You can create a new Shared Spaces with the following request:

Method	Endpoint	Description
`POST`	`/shared-spaces`	Creates a new Shared Space

Update Shared Space

Method	Endpoint	Description
`PATCH`	`/shared-spaces/{shareId}`	Updates a specific Shared Space (specified by `{shareId}`).

Archive a Shared Space and disable all external access:

cURL
JavaScript
Python

curl -X PATCH 'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/95e63d4a4d049cb63fea74de4bcb2c90' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "ARCHIVED Marketing & Revenue Collaboration",
    "status": "ARCHIVED",
    "isExternalUploadAllowed": false,
    "isExternalInviteAllowed": false,
    "isExternalDownloadAllowed": false,
    "description": "ARCHIVED"
  }'

const response = await fetch(
  'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/95e63d4a4d049cb63fea74de4bcb2c90',
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer {access_token}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'ARCHIVED Marketing & Revenue Collaboration',
      status: 'ARCHIVED',
      isExternalUploadAllowed: false,
      isExternalInviteAllowed: false,
      isExternalDownloadAllowed: false,
      description: 'ARCHIVED',
    }),
  }
);
const sharedSpace = await response.json();

import requests

response = requests.patch(
    'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/95e63d4a4d049cb63fea74de4bcb2c90',
    headers={
        'Authorization': 'Bearer {access_token}',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'ARCHIVED Marketing & Revenue Collaboration',
        'status': 'ARCHIVED',
        'isExternalUploadAllowed': False,
        'isExternalInviteAllowed': False,
        'isExternalDownloadAllowed': False,
        'description': 'ARCHIVED'
    }
)
shared_space = response.json()

Response

{
  "id": "95e63d4a4d049cb63fea74de4bcb2c90",
  "title": "ARCHIVED Marketing & Revenue Collaboration",
  "publicUri": "marketing-space",
  "publicUrl": "https://{{subdomain}}.showpad.com/s/marketing-space",
  "status": "ARCHIVED",
  "isExternalUploadAllowed": false,
  "isExternalInviteAllowed": false,
  "isExternalDownloadAllowed": false,
  "createdAt": "2025-01-09T11:38:06.000Z",
  "lastActivityAt": "2025-01-09T11:38:07.000Z",
  "archivedAt": "2025-01-09T11:51:24.271Z",
  "description": "ARCHIVED",
  "owner": {
    "userId": "b5f5e881324f61479002be5cda41b1ca"
  },
  "theme": {
    "id": "51be10f001cd0303a4e308a22e051ecbcb1a5b0ba9ae9e5bb38167ed0c5b3a09"
  }
}

Retrieve Shared Spaces

Single Shared Space

Method	Endpoint	Description
`GET`	`/shared-spaces/{shareId}`	Returns a single Shared Space (specified by `{shareId}`).

cURL
JavaScript
Python

curl -X GET 'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/b5f5e881324f61479002be5cda41b1ca' \
  -H 'Authorization: Bearer {access_token}'

const response = await fetch(
  'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/b5f5e881324f61479002be5cda41b1ca',
  {
    headers: {
      Authorization: 'Bearer {access_token}',
    },
  }
);
const sharedSpace = await response.json();

import requests

response = requests.get(
    'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/b5f5e881324f61479002be5cda41b1ca',
    headers={
        'Authorization': 'Bearer {access_token}'
    }
)
shared_space = response.json()

Response

{
  "id": "95e63d4a4d049cb63fea74de4bcb2c90",
  "title": "Marketing & Revenue Collaboration",
  "publicUri": "marketing-space",
  "publicUrl": "https://{{subdomain}}.showpad.com/s/marketing-space",
  "status": "ACTIVE",
  "isExternalUploadAllowed": false,
  "isExternalInviteAllowed": true,
  "isExternalDownloadAllowed": true,
  "createdAt": "2025-01-09T11:38:06.000Z",
  "lastActivityAt": "2025-01-09T11:38:07.000Z",
  "archivedAt": null,
  "description": "Custom description from request",
  "owner": {
    "userId": "b5f5e881324f61479002be5cda41b1ca"
  },
  "theme": {
    "id": "51be10f001cd0303a4e308a22e051ecb5385615a564eeef116fec329acb33276"
  }
}

List of Shared Spaces

You can retreive a list of all the Shared Spaces a user participates in or owns with the following request:

Method	Endpoint	Description
`GET`	`/shared-spaces`	Returns a list of all Shared Spaces. The scope of the returned list is determined by the user's role.

Authorization and Scopes

This endpoint uses role-based access control. The list of Shared Spaces returned will differ based on the role assigned to the API key's owner:

Role	Access Rule
Administrator	Returns all Shared Spaces.
Manager	Returns all Shared Spaces that you own or are a member of, plus all Shared Spaces belonging to users who report to you.
User	Returns only the Shared Spaces that you are a member of.

tip

You can filter the list by participant email, owner email, title, etc.

Delete Shared Space

Method	Endpoint	Description
`DELETE`	`/shared-spaces/{sharedSpaceId}`	Permanently removes a single Shared Space (specified by `{sharedSpaceId}`).

cURL
JavaScript
Python

curl -X DELETE 'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/2132ee1e1f0495ffa445041b52cc062e' \
  -H 'Authorization: Bearer {access_token}'

const response = await fetch(
  'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/2132ee1e1f0495ffa445041b52cc062e',
  {
    method: 'DELETE',
    headers: {
      Authorization: 'Bearer {access_token}',
    },
  }
);
// Returns 204 No Content on success

import requests

response = requests.delete(
    'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/2132ee1e1f0495ffa445041b52cc062e',
    headers={
        'Authorization': 'Bearer {access_token}'
    }
)
# Returns 204 No Content on success

Response

204 No Content

Transfer Shared Space Ownership

In scenarios such as a user being deactivated or changes within the account team, it becomes necessary to transfer ownership of Shared Spaces. There are two ways to transfer ownership of a Shared Space:

via the Showpad Web App - Only the current owner can transfer the ownership.
via API - The current owner or an admin can transfer the ownership. The new owner of the Shared Space will receive a notification of the transfer of ownership.

Method	Endpoint	Description
`POST`	`/shared-spaces/{shared space ID}/transfer-ownership`	Transfers the ownership of a Shared Space from one user to another. The Shared Space's new owner's ID is specified in the request body.

You need:

The Shared Space ID
The user ID of the new owner

cURL
JavaScript
Python

curl -X POST 'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/{sharedSpaceId}/transfer-ownership' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "b5f5e881324f61479002be5cda41b1ca"
  }'

const response = await fetch(
  'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/{sharedSpaceId}/transfer-ownership',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer {access_token}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      userId: 'b5f5e881324f61479002be5cda41b1ca',
    }),
  }
);
// Returns 204 No Content on success

import requests

response = requests.post(
    'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/{sharedSpaceId}/transfer-ownership',
    headers={
        'Authorization': 'Bearer {access_token}',
        'Content-Type': 'application/json'
    },
    json={
        'userId': 'b5f5e881324f61479002be5cda41b1ca'
    }
)
# Returns 204 No Content on success

Response

204 No Content

Troubleshooting

Code	Cause	Solution
`400 Bad Request`	Missing required field (`userId` or `title`)	Include all required fields in the request body
`400 Bad Request`	`publicUri` already in use	Choose a unique URI or omit to auto-generate
`400 Bad Request`	Invalid template ID	Verify the template ID exists and is active
`403 Forbidden`	Insufficient permissions	Ensure the API token has admin rights or the user owns the Shared Space
`404 Not Found`	Shared Space ID not found	Verify the Shared Space ID exists

For a complete list of error codes and response formats, see Error Codes.

Next Steps

Shared Space Content: Add and manage assets within a Shared Space.
Shared Space Templates: Create templates for consistent Shared Space creation.
Mutual Action Plan: Add collaborative action plans to Shared Spaces.
Shares: Create one-time shareable links for content.

When to use the API​

Auto-creation Notifications​

Base Endpoint​

The Shared Space object​

Create and Update​

Request Body​

Create Shared Space​

Update Shared Space​

Retrieve Shared Spaces​

Single Shared Space​

List of Shared Spaces​

Authorization and Scopes​

Delete Shared Space​

Transfer Shared Space Ownership​

Troubleshooting​

Next Steps​

When to use the API

Auto-creation Notifications

Base Endpoint

The Shared Space object

Create and Update

Request Body

Create Shared Space

Update Shared Space

Retrieve Shared Spaces

Single Shared Space

List of Shared Spaces

Authorization and Scopes

Delete Shared Space

Transfer Shared Space Ownership

Troubleshooting

Next Steps