Shared Space Content

You can programmatically add content (files, folders, and individual pages from multi-page documents) into an existing Shared Space to enrich buyer experiences and keep content aligned with the sales process.

Adding Content to Shared Spaces via API helps keep Shared Spaces relevant and up-to-date, supports scalable content workflows, and ensures buyers always have access to the most impactful materials when and where they need them.

Key Benefits

Enhance Buyer Engagement: Keep Shared Spaces fresh and relevant by programmatically adding key assets throughout the deal cycle.
Streamline Workflows: Add files, folders, or document pages directly via API to existing Shared Spaces to eliminate manual updates and save time.
Maintain Structure and Clarity: Automatically build organized folder hierarchies to deliver a clear, consistent content experience.
Handle Errors Gracefully: Ensure reliability with robust support for partial success and detailed error reporting.
Stay In Sync: Trigger webhook notifications to keep systems and teams updated as new content is added.

Concepts

Handling & Processing

	Description
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"
}
```
```

Requests Overview

Prerequisites

Plan: Ultimate | Advanced or Expert
Permissions: Administrator access to Showpad's Admin App
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.

Request Body

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

Root Level Fields

Fields	Description	Required
`items`	Array of items to add to the Shared Space	True

Item Types & Fields

Type	Fields	Description	Required
`asset`	`assetId`	The unique identifier of the asset to add.	True
	`page`	Specifies the page number to add from a multi-page document. Note: Uses 1-based indexing (i.e., the first page is 1).	False
`folder`	`name`	The name of the folder. Note: 255 characters maximum	True
	`description`	A description of the folder .	False
	`folderItems`	An array of nested items within the folder.	False

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	Description
`assetSuccessCount`	Number of assets that were successfully added .
`assetFailureCount`	Number of assets that failed to be added.

Failed Items Array

Each failed item includes identifying and diagnostic information.

Field	Description
`type`	The type of item that failed.
`assetId`	Identifier of the asset that failed.
`reason`	Reason for the failure. See Troubleshooting section.
`page`	(optional) Specific page number if the failure is page-related.
`name`	(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 -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"
    }
  ]
}'

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 -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"
              }
            ]
          }
        ]
      }
    ]
  }'

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 -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
    }
  ]
}'

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.

Example

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

Request

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"
    }
  ]
}'

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"
    }
  ]
}

Concepts​

Handling & Processing​

Webhook Notifications​

Initiators​

Requests Overview​

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​

Example​

Concepts

Handling & Processing

Webhook Notifications

Initiators

Requests Overview

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

Example