Shared Space Content

Add assets, folders, and document pages to Shared Spaces programmatically. Keep buyer-facing content fresh and aligned with the sales process through automated workflows.

What you'll learn:

How to add assets and folders to a Shared Space
How to build nested folder hierarchies
How to handle partial success and failed items

TL;DR

Add content? Use POST /shared-spaces/{id}/items with an items array
Create folders? Use type: "folder" with optional folderItems for nesting
Add specific pages? Include page number (1-based) with type: "asset"

When to use the API

Automate Content Updates	Build Folder Structures	Sync from External Systems	Handle Partial Failures
Add assets to Shared Spaces when deals progress in your CRM.	Create organized folder hierarchies programmatically.	Push content from DAM or other systems into Shared Spaces.	Process bulk operations with detailed error reporting.

Concepts

Folder Handling

Folder nesting supports multiple levels through the folderItems property. Empty folders are allowed and can be created.

Webhook Notifications

tip

To receive notifications for content added to Shared Spaces via API, subscribe to the Content added to Shared Space (V2) webhook.

When content is added to a Shared Space via the API, it triggers webhook notifications that external systems can consume to stay in sync. For large operations, these notifications are batched (up to 1000 items per event).

Each webhook payload includes detailed information about the added items, along with context about the initiator who performed the action.

Initiators

Initiators indicate who triggers an action. The initiator object replaces the previous participant field in events to support actions from different sources (participants, admins, or apps).

The API supports three types of initiators, each with different levels of access and context:

PARTICIPANT: A user who is a participant in the Shared Space. This initiator type can perform actions as themselves and their activity is visible to other participants (e.g., when uploading content).

{
"type": "PARTICIPANT",
"participant": {
  "id": "e3dff281ad48421fb32de1cbab3a627f",
  "email": "participant@example.com",
  "userId": "d40cce9cdc0945298b8120ca7de4adc7",
  "firstName": "Anna",
  "lastName": "Doe",
  "company": "Acme Inc.",
  "jobTitle": "Manager"
  }
}

ADMIN: An admin user who is not a participant in the Shared Space. This initiator type can perform administrative tasks programmatically but does not appear in the participant list.
```
{
"type": "ADMIN",
"userId": "d40cce9cdc0945298b8120ca7de4adc7"
}
```
APP: An application or integration using an API token to make calls. This initiator represents a system-level integration, not a specific user. Actions performed by an APP are typically invisible to participants and useful for automated workflows.
```
{
  "type": "APP",
  "userId": "d40cce9cdc0945298b8120ca7de4adc7"
}
```

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 content 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.

Request Body

Your request must include required root-level fields, along with well-defined item types and their corresponding fields.

Root Level Fields

Field	Data Type	Description	Required
`items`	`array<object>`	Array of items to add to the Shared Space.	Yes

Item Types & Fields

Type	Field	Data Type	Description	Required
`asset`	`assetId`	`string`	The unique identifier of the asset to add.	Yes
	`page`	`integer`	The page number to add from a multi-page document. Uses 1-based indexing (first page is 1).	No
`folder`	`name`	`string`	The name of the folder. Max 255 characters.	Yes
	`description`	`string`	A description of the folder.	No
	`folderItems`	`array<object>`	An array of nested items within the folder.	No

Request Structure

Each item in your request must follow one of the supported structures: asset or folder.

The request body must include an items array containing one or more of these item types:

{
  "items": [
    {
      // one of the item types (asset, folder)
    }
  ]
}

Asset Item - Use this to add an individual asset to the Shared Space.
```
{
  "type": "asset",
  "assetId": "string (required)",
  "page": "number (optional, 1-based)"
}
```
info
You can use the List all assets endpoint to retrieve a list of all assets and their IDs.

Folder Item - Use this to create a new folder. Folders can contain assets or other folders.

{
  "type": "folder",
  "name": "string (required)",
  "description": "string (optional)",
  "folderItems": [
    // one of the item types
  ]
}

Nested hierarchy: You can nest folders recursively using the folderItems array to build structured hierarchies:

{
"items": [
  {
    "type": "folder",
    "name": "Parent Folder",
    "folderItems": [
      {
        "type": "folder",
        "name": "Child Folder",
        "folderItems": [
          {
            "type": "asset",
            "assetId": "asset-abc123"
            }
          ]
        }
      ]
    }
  ]
}

Response Fields

Summary Object

Responses include a summary of success/failure and detailed information about any failed items.

Field	Data Type	Description
`assetSuccessCount`	`integer`	Number of assets that were successfully added.
`assetFailureCount`	`integer`	Number of assets that failed to be added.

Failed Items Array

Each failed item includes identifying and diagnostic information.

Field	Data Type	Description
`type`	`string`	The type of item that failed.
`assetId`	`string`	Identifier of the asset that failed.
`reason`	`string`	Reason for the failure. See Troubleshooting section.
`page`	`integer`	(optional) Specific page number if the failure is page-related.
`name`	`string`	(optional) Name of the failed asset, if available.

Add Items to Shared Space

Method	Endpoint	Description
`POST`	`/shared-spaces/{shareId}/items`	Adds items to a specific Shared Space (specified by `{shareId}`). You can use the List of Shared Spaces endpoint to retrieve the ID.

tip

To improve performance, consider breaking large operations into smaller batches, as processing many items at once can significantly increase processing time.

Recommended batch size: 0-100 items

Asset Example

This example demonstrates adding a specific asset to a designated Shared Space.

Request

cURL
JavaScript
Python

curl -X POST \
'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items' \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json' \
--data '{
  "items": [
    {
      "type": "asset",
      "assetId": "a5f01a23f94aaf6195c1012694a404ea"
    }
  ]
}'

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        type: 'asset',
        assetId: 'a5f01a23f94aaf6195c1012694a404ea',
      },
    ],
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {
            "type": "asset",
            "assetId": "a5f01a23f94aaf6195c1012694a404ea"
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response

{
  "summary": {
    "assetSuccessCount": 1,
    "assetFailureCount": 0
  },
  "failedItems": []
}

tip

Looking to add new assets to Showpad via the API for use in your Shared Spaces? Check out the Asset Management section for guidance on how to:

Folder Example

This example demonstrates how to create a nested folder structure.

Request

cURL
JavaScript
Python

curl -X POST \
'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items' \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json' \
--data '{
  "items": [
    {
      "type": "folder",
      "name": "Marketing Materials",
      "description": "Q4 2024 Marketing Assets",
      "folderItems": [
        {
          "type": "asset",
          "assetId": "asset123"
        },
        {
          "type": "folder",
          "name": "Presentations",
          "folderItems": [
            {
              "type": "asset",
              "assetId": "asset456"
            }
          ]
        }
      ]
    }
  ]
}'

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        type: 'folder',
        name: 'Marketing Materials',
        description: 'Q4 2024 Marketing Assets',
        folderItems: [
          {
            type: 'asset',
            assetId: 'asset123',
          },
          {
            type: 'folder',
            name: 'Presentations',
            folderItems: [
              {
                type: 'asset',
                assetId: 'asset456',
              },
            ],
          },
        ],
      },
    ],
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {
            "type": "folder",
            "name": "Marketing Materials",
            "description": "Q4 2024 Marketing Assets",
            "folderItems": [
                {
                    "type": "asset",
                    "assetId": "asset123"
                },
                {
                    "type": "folder",
                    "name": "Presentations",
                    "folderItems": [
                        {
                            "type": "asset",
                            "assetId": "asset456"
                        }
                    ]
                }
            ]
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response

{
  "summary": {
    "assetSuccessCount": 2,
    "assetFailureCount": 0
  },
  "failedItems": []
}

Pages Example

This example demonstrates adding a specific page from a multi-page asset into a designated Shared Space.

Request

cURL
JavaScript
Python

curl -X POST \
'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items' \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json' \
--data '{
  "items": [
    {
      "type": "asset",
      "assetId": "multi-page-doc-123",
      "page": 3
    }
  ]
}'

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        type: 'asset',
        assetId: 'multi-page-doc-123',
        page: 3,
      },
    ],
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {
            "type": "asset",
            "assetId": "multi-page-doc-123",
            "page": 3
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response

{
  "summary": {
    "assetSuccessCount": 1,
    "assetFailureCount": 0
  },
  "failedItems": []
}

Troubleshooting

Asset Validation

Reason Code	Description	Occurs When
`NON_SHAREABLE`	Asset has sharing restrictions	The asset is not shareable, preventing it from being added to Shared Spaces.
`INACCESSIBLE`	Asset is not accessible to the user	The user does not have the correct permissions to: view the asset, or access the library where the asset is.
`ASSET_NOT_FOUND`	Asset ID does not exist	The specified `assetId` does not match any asset in the system.
`ARCHIVED`	Asset is archived and unavailable	Archived assets cannot be added to Shared Spaces.
`LOCKED_RANGE_INCOMPLETE`	Required page range is incomplete	For documents with locked page selections, not all required pages were specified.
`ONLY_ENTIRE_DOCUMENT_ALLOWED`	Page selection not permitted	The asset must be shared as a complete document; individual page selection is not supported.

Partial Success Example

This example demonstrates a partial success. The request attempts to add three assets to a Shared Space, but only one is successfully added because one asset has been archived and the other cannot be found.

Request

cURL
JavaScript
Python

curl -X POST \
'https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items' \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json' \
--data '{
  "items": [
    {
      "type": "asset",
      "assetId": "valid-asset-123"
    },
    {
      "type": "asset",
      "assetId": "archived-asset-456"
    },
    {
      "type": "asset",
      "assetId": "non-existent-789"
    }
  ]
}'

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      { type: 'asset', assetId: 'valid-asset-123' },
      { type: 'asset', assetId: 'archived-asset-456' },
      { type: 'asset', assetId: 'non-existent-789' },
    ],
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/shared-spaces/abc123def456/items"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"type": "asset", "assetId": "valid-asset-123"},
        {"type": "asset", "assetId": "archived-asset-456"},
        {"type": "asset", "assetId": "non-existent-789"}
    ]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response

{
  "summary": {
    "assetSuccessCount": 1,
    "assetFailureCount": 2
  },
  "failedItems": [
    {
      "type": "asset",
      "assetId": "archived-asset-456",
      "reason": "ARCHIVED"
    },
    {
      "type": "asset",
      "assetId": "non-existent-789",
      "reason": "ASSET_NOT_FOUND"
    }
  ]
}

For more error codes and troubleshooting guidance, see Error Codes.

Next Steps

Shared Space Templates: Use templates for consistent Shared Space creation
Mutual Action Plans: Add collaborative task lists to Shared Spaces
Quick Actions: Configure quick action buttons for Shared Spaces

Was this page helpful?

When to use the API​

Concepts​

Folder Handling​

Webhook Notifications​

Initiators​

Base Endpoint​

Request Body​

Root Level Fields​

Item Types & Fields​

Request Structure​

Response Fields​

Summary Object​

Failed Items Array​

Add Items to Shared Space​

Asset Example​

Folder Example​

Pages Example​

Troubleshooting​

Asset Validation​

Partial Success Example​

Next Steps​

When to use the API

Concepts

Folder Handling

Webhook Notifications

Initiators

Base Endpoint

Request Body

Root Level Fields

Item Types & Fields

Request Structure

Response Fields

Summary Object

Failed Items Array

Add Items to Shared Space

Asset Example

Folder Example

Pages Example

Troubleshooting

Asset Validation

Partial Success Example

Next Steps