Content Recommendations

The Showpad API provides ranked lists of recommended assets based on input parameters like date ranges, tags, and activity type.

What you'll learn:

Retrieve new, popular, trending, and updated assets
Get experience recommendations
Display Home Screen recommendations in custom integrations

TL;DR

What's new? Use GET /recommendations/new. Assets added within a date range.
What's popular? Use GET /recommendations/popular. Most viewed assets.
What's trending? Use GET /recommendations/trending. Assets with recent view spikes.
Home Screen content? Use GET /recommendations/homescreen. Matches the user's Home Screen.

When to use the API

Use the Showpad API for recommendations when you need to:

Surface recommendations	Build dashboards	Personalize integrations	Analyze trends
Display the same content suggestions users see on their Home Screen	Show popular or trending assets in custom reporting tools	Recommend relevant content based on user activity	Identify which assets are gaining traction over time

Query Parameters

This service relies heavily on query parameters. You must ensure that the values of all query parameters use URL encoding (as demonstrated in the examples in this documentation).

All date parameters accept these formats:

Format	Example	Description
UNIX timestamp	`1672531200`	Seconds since Jan 1, 1970 UTC
Date	`2023-01-01`	Year-month-day
Date and time	`2023-01-01 09:30:00`	Year-month-day hours:minutes:seconds

Common Parameters

Parameter	Type	Description
`startedAt`	string	Calculate results using activity after this date (default: 1 year ago)
`endedAt`	string	Calculate results using activity before this date (default: now)
`activityScope`	string	Base calculations on `viewed` or `shared` activity (default: `viewed`)
`userScope`	string	Scope to `user` (current user only) or `global` (all users with access) (default: `global`)
`tagIds`	string	Comma-separated tag IDs to filter results
`conjunctiveTagIds`	string	Comma-separated tag IDs - assets must have ALL specified tags
`excludedTagIds`	string	Comma-separated tag IDs to exclude from results
`limit`	integer	Maximum number of results to return (default: 10)

Prerequisites

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

Base Endpoint

The base endpoint for v3 requests is:

https://{{subdomain}}.showpad.biz/api/v3

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

CORS

Showpad adopts a strict approach for cross-origin requests. Only requests from your valid Showpad domain are allowed.

Recommendation Endpoints

See the API v3 reference for more in-depth information about the recommendations endpoints.

	Endpoint	Description
New assets	`/recommendations/assets/new`	Assets recently assigned to the user that they haven't viewed yet. Use to surface fresh content and drive engagement with newly available materials.
Popular assets	`/recommendations/assets/popular`	Assets with sustained, long-term engagement (views, shares, or downloads). Use to highlight top-performing content, recommend frequently accessed assets, or inform content strategy.
Trending assets	`/recommendations/assets/trending`	Assets with rising engagement based on recent activity. Use to surface timely content, highlight assets receiving increased attention, or filter by tags, activity type, or time window.
Updated assets	`/recommendations/assets/updated`	Assets that have been revised since the user last viewed them. Use to notify users of refreshed content they've previously engaged with.
New experiences	`/recommendations/experiences/new`	Experiences to which the user has been recently assigned.
Popular experiences	`/recommendations/experiences/popular`	Experiences to which the user is assigned and which is popular with users that have access to it.
Home Screen recommendations	`/users/me/recommendations?context=homescreen`	Provides the same recommendations as available in your Home Screen. A single call that combines the different models. An asset that has been selected by a previous recommendation model, cannot be recommended again.

Default values

limit defaults to 10 if not specified
activityScope defaults to "viewed" if not specified

Examples

New Assets

This request retrieves the top 25 assets that are newly available to the user with the following parameters:

assignedAfter - Assets assigned to the user after March 1, 2023
notViewedAfter - Exclude assets after March 3, 2023
conjunctiveTagIds - Only include tags with the given IDs
limit - Return no more than 25 assets

Request

cURL
JavaScript
Python

curl --request GET \
    --url 'https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/new?assignedAfter=2023-03-01&notViewedAfter=2023-03-03&conjunctiveTagIds=df391e1da6ed4db8a8085838f7abd130%2C83a5a807b3c487c91f39d1c3da00b5d6&limit=25' \
    --header 'Authorization: Bearer TOKEN' \
    --header 'Content-Type: application/json'

const response = await fetch(
  'https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/new?' +
    new URLSearchParams({
      assignedAfter: '2023-03-01',
      notViewedAfter: '2023-03-03',
      conjunctiveTagIds: 'df391e1da6ed4db8a8085838f7abd130,83a5a807b3c487c91f39d1c3da00b5d6',
      limit: '25',
    }),
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer TOKEN',
      'Content-Type': 'application/json',
    },
  }
);

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

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/new"
params = {
    "assignedAfter": "2023-03-01",
    "notViewedAfter": "2023-03-03",
    "conjunctiveTagIds": "df391e1da6ed4db8a8085838f7abd130,83a5a807b3c487c91f39d1c3da00b5d6",
    "limit": 25
}
headers = {
    "Authorization": "Bearer TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

{
  "meta": {
    "count": 2
  },
  "response": {
    "items": [
      {
        "id": "cc55b0cf8eef46f71d3a6398734e0611",
        "name": "Product Overview.pdf",
        "resourcetype": "asset"
      },
      {
        "id": "422bb79a5e8347d1bf93a5d3306bda65",
        "name": "Sales Deck Q1.pptx",
        "resourcetype": "asset"
      }
    ]
  }
}

Popular Assets

This request returns the 10 most popular assets in Q4 2022 using the following parameters:

startedAt - Calculate asset popularity after October 1, 2022
endedAt - Calculate asset popularity before December 31, 2022
activityScope - Calculate asset popularity based on the number of shares
excludedTagIds - Exclude assets having either of the given tag IDs
limit - Return no more than 10 assets

Request

cURL
JavaScript
Python

curl --request GET \
    --url 'https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/popular?startedAt=2022-10-01&endedAt=2022-12-31&activityScope=shared&excludedTagIds=df391e1da6ed4db8a8085838f7abd130%2C83a5a807b3c487c91f39d1c3da00b5d6&limit=10' \
    --header 'Authorization: Bearer TOKEN' \
    --header 'Content-Type: application/json'

const response = await fetch(
  'https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/popular?' +
    new URLSearchParams({
      startedAt: '2022-10-01',
      endedAt: '2022-12-31',
      activityScope: 'shared',
      excludedTagIds: 'df391e1da6ed4db8a8085838f7abd130,83a5a807b3c487c91f39d1c3da00b5d6',
      limit: '10',
    }),
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer TOKEN',
      'Content-Type': 'application/json',
    },
  }
);

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

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/popular"
params = {
    "startedAt": "2022-10-01",
    "endedAt": "2022-12-31",
    "activityScope": "shared",
    "excludedTagIds": "df391e1da6ed4db8a8085838f7abd130,83a5a807b3c487c91f39d1c3da00b5d6",
    "limit": 10
}
headers = {
    "Authorization": "Bearer TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

{
  "meta": {
    "count": 2
  },
  "response": {
    "items": [
      {
        "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "score": 245.5,
        "model": "content-asset-popular",
        "content": {
          "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
          "displayName": "Q4 Sales Playbook.pdf",
          "type": "document"
        }
      },
      {
        "id": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
        "score": 198.3,
        "model": "content-asset-popular",
        "content": {
          "id": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
          "displayName": "Product Demo Video.mp4",
          "type": "video"
        }
      }
    ]
  }
}

This request returns the top 25 trending assets for Q4 2022 using the following parameters:

startedAt - Calculate asset popularity after October 1, 2022
endedAt - Calculate asset popularity before December 31, 2022
limit - Return no more than 25 assets

Request

cURL
JavaScript
Python

curl --request GET \
    --url 'https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/trending?startedAt=2022-10-01&endedAt=2022-12-31&limit=25' \
    --header 'Authorization: Bearer TOKEN' \
    --header 'Content-Type: application/json'

const response = await fetch(
  'https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/trending?' +
    new URLSearchParams({
      startedAt: '2022-10-01',
      endedAt: '2022-12-31',
      limit: '25',
    }),
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer TOKEN',
      'Content-Type': 'application/json',
    },
  }
);

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

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/trending"
params = {
    "startedAt": "2022-10-01",
    "endedAt": "2022-12-31",
    "limit": 25
}
headers = {
    "Authorization": "Bearer TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

{
  "meta": {
    "count": 2
  },
  "response": {
    "items": [
      {
        "id": "c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
        "score": 12.7,
        "model": "content-asset-trending",
        "content": {
          "id": "c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
          "displayName": "New Feature Announcement.pdf",
          "type": "document"
        }
      },
      {
        "id": "d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9",
        "score": 9.4,
        "model": "content-asset-trending",
        "content": {
          "id": "d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9",
          "displayName": "Competitive Analysis Q4.pptx",
          "type": "document"
        }
      }
    ]
  }
}

Updated Assets

This request returns updated assets with the following parameter:

updatedAfter - Assets updated after 2023-02-15 11:30:00

Request

cURL
JavaScript
Python

curl --request GET \
    --url 'https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/updated?updatedAfter=2023-02-15%2011%3A30%3A00' \
    --header 'Authorization: Bearer TOKEN' \
    --header 'Content-Type: application/json'

const response = await fetch(
  'https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/updated?' +
    new URLSearchParams({
      updatedAfter: '2023-02-15 11:30:00',
    }),
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer TOKEN',
      'Content-Type': 'application/json',
    },
  }
);

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

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/updated"
params = {
    "updatedAfter": "2023-02-15 11:30:00"
}
headers = {
    "Authorization": "Bearer TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

{
  "meta": {
    "count": 1
  },
  "response": {
    "items": [
      {
        "id": "e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
        "score": 1.0,
        "model": "content-asset-updated",
        "content": {
          "id": "e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
          "displayName": "Pricing Guide 2023.pdf",
          "type": "document"
        }
      }
    ]
  }
}

New Experiences

This request returns the top 10 most recent experiences to which the user has been assigned using the following parameter:

assignedAfter - Only include experiences that have been assigned to the user after January 1, 2023

Request

cURL
JavaScript
Python

curl --request GET \
    --url 'https://{{subdomain}}.showpad.biz/api/v3/recommendations/experiences/new?assignedAfter=2023-01-01' \
    --header 'Authorization: Bearer TOKEN' \
    --header 'Content-Type: application/json'

const response = await fetch(
  'https://{{subdomain}}.showpad.biz/api/v3/recommendations/experiences/new?' +
    new URLSearchParams({
      assignedAfter: '2023-01-01',
    }),
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer TOKEN',
      'Content-Type': 'application/json',
    },
  }
);

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

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/recommendations/experiences/new"
params = {
    "assignedAfter": "2023-01-01"
}
headers = {
    "Authorization": "Bearer TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

{
  "meta": {
    "count": 2
  },
  "response": {
    "items": [
      {
        "id": "f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1",
        "score": 1.0,
        "model": "content-experience-new",
        "content": {
          "id": "f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1",
          "displayName": "Product Launch 2023",
          "type": "experience"
        }
      },
      {
        "id": "g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2",
        "score": 1.0,
        "model": "content-experience-new",
        "content": {
          "id": "g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2",
          "displayName": "Sales Enablement Kit",
          "type": "experience"
        }
      }
    ]
  }
}

Popular Experiences

This request returns the top 10 most popular experiences in Q1 2022 to which the user is assigned using the following parameters:

startedAt - Calculate experience popularity after January 1, 2022
endedAt - Calculate experience popularity before March 31, 2022

Request

cURL
JavaScript
Python

curl --request GET \
    --url 'https://{{subdomain}}.showpad.biz/api/v3/recommendations/experiences/popular?startedAt=2022-01-01&endedAt=2022-03-31' \
    --header 'Authorization: Bearer TOKEN' \
    --header 'Content-Type: application/json'

const response = await fetch(
  'https://{{subdomain}}.showpad.biz/api/v3/recommendations/experiences/popular?' +
    new URLSearchParams({
      startedAt: '2022-01-01',
      endedAt: '2022-03-31',
    }),
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer TOKEN',
      'Content-Type': 'application/json',
    },
  }
);

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

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/recommendations/experiences/popular"
params = {
    "startedAt": "2022-01-01",
    "endedAt": "2022-03-31"
}
headers = {
    "Authorization": "Bearer TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

{
  "meta": {
    "count": 2
  },
  "response": {
    "items": [
      {
        "id": "h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3",
        "score": 156.2,
        "model": "content-experience-popular",
        "content": {
          "id": "h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3",
          "displayName": "Enterprise Solutions Overview",
          "type": "experience"
        }
      },
      {
        "id": "i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
        "score": 98.7,
        "model": "content-experience-popular",
        "content": {
          "id": "i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
          "displayName": "Customer Success Stories",
          "type": "experience"
        }
      }
    ]
  }
}

Home Screen Recommendations

This request returns the homescreen recommendations for the current user.

Request

cURL
JavaScript
Python

curl --request GET \
    --url 'https://{{subdomain}}.showpad.biz/api/v3/users/me/recommendations.json' \
    --header 'Authorization: Bearer TOKEN' \
    --header 'Content-Type: application/json'

const response = await fetch('https://{{subdomain}}.showpad.biz/api/v3/users/me/recommendations.json', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer TOKEN',
    'Content-Type': 'application/json',
  },
});

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

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/users/me/recommendations.json"
headers = {
    "Authorization": "Bearer TOKEN",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Response

{
  "meta": {
    "count": 4
  },
  "response": {
    "items": [
      {
        "id": "j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5",
        "score": 1.0,
        "model": "content-asset-new",
        "content": {
          "id": "j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5",
          "displayName": "Weekly Newsletter.pdf",
          "type": "document"
        }
      },
      {
        "id": "k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
        "score": 245.5,
        "model": "content-asset-popular",
        "content": {
          "id": "k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
          "displayName": "Sales Playbook.pdf",
          "type": "document"
        }
      },
      {
        "id": "l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7",
        "score": 12.7,
        "model": "content-asset-trending",
        "content": {
          "id": "l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7",
          "displayName": "New Feature Guide.pdf",
          "type": "document"
        }
      },
      {
        "id": "m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8",
        "score": 1.0,
        "model": "content-asset-updated",
        "content": {
          "id": "m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8",
          "displayName": "Pricing Overview.pdf",
          "type": "document"
        }
      }
    ]
  }
}

Troubleshooting

If a request returns empty results, adjust the date range or remove restrictive filters like conjunctiveTagIds. For a complete list of error codes and response formats, see Error Codes.

Next Steps

Now that you understand content recommendations, explore these related topics:

Buyer Engagement: Create shareable links and track recipient engagement.
Seller Effectiveness: Configure CRM recommendation rules for sales reps.
API Reference: Full API specification for all recommendation endpoints.

Was this page helpful?

When to use the API​

Query Parameters​

Common Parameters​

Base Endpoint​

Recommendation Endpoints​

Examples​

New Assets​

Popular Assets​

Trending Assets​

Updated Assets​

New Experiences​

Popular Experiences​

Home Screen Recommendations​

Troubleshooting​

Next Steps​

When to use the API

Query Parameters

Common Parameters

Base Endpoint

Recommendation Endpoints

Examples

New Assets

Popular Assets

Trending Assets

Updated Assets

New Experiences

Popular Experiences

Home Screen Recommendations

Troubleshooting

Next Steps