Content Reporting

Showpad's Content Reporting API service (also known as the Export API), enables you to generate and download everything you see in the Reports section of Showpad's Online Platform (OP) such as:

• when was an asset viewed,
• how long an asset was viewed,
• who shared which asset and with whom,
• who participates in a Shared Space,
• and more.

You can download the more granular raw data as a CSV or JSON file so you can use it in your own BI solution, combine it with other data sources in your organization, and run custom analysis on it.

If activated, the anonymization of usernames and IDs is respected. You can still join tables to analyze the data.

Data Model

Export Tables

Nearly all exports begin with the Events table. This table is the central table for exporting content data. All content-related actions a user can make are tracked as in this table. All other export tables (lookup) relate to the Events (fact) table.

The following is a description of each of the export tables.

A - C - D - E - S - T - U

	Table	Content	Description
A	Assets	List of assets.
	Asset-authors	List of authors for assets.	Authors are also users, so the author information is found in the users call.
	Asset-countries	List of asset countries.
	Asset-languages	List of languages assigned for an asset.
	Asset-tags	Many to many relation between assets and tags.
C	Channels (legacy name for Experiences)	List of Experiences an asset was opened in.	Only recorded for Classic Experiences and simple folders. It does not include Smart Folders.
	Channel-usergroups	Usergroups assigned to an experience
	Channel-users	Users assigned to an experience
	Collections	List of user collections.
	Collection-items	List of assets within a collection.
	Contacts	The contacts you send to.
D	Devices	List of devices used.	Can be the device of the user or the device of the contact depending on relevant event type
	Divisions	Division the asset belongs to.	Assets belong to a library (which is a division). Instances can have one or more divisions. Personal files of users are also a division that is only accessible by those users.
	Division_usergroups	Usergroups assigned to a division.	If you want to report by divisions, this is the only correct relation for which users belong to which division.
E	Events	All events of a user or recipient.	Main fact table. All the other tables are lookup tables with more information. See table underneath to see which lookup table is relevant for what event type.
S	Shares	List of shares. Every message sent out to prospects is a share.	One share can contain multiple assets.
	Sharedspaces	All shared spaces created in the account.
	Sharedspaceparticipants	Participants of a shared space.	All participants are created as users.
	Sharedspace-items	Asset items located in a shared space.
T	Tags	List of tags.
	Tagcategories	List of tag categories.	Tags can be grouped in one or more categories. Categories can be grouped in other categories.
	Tagcategory-tags	Many to many relation between tag categories and tags.
U	Users	List of users.
	Usergroups	List of user groups.
	User-usergroups	Many to many relation between users and usergroups.

Requests

Prerequisites

• Showpad Ultimate package
• Access to Showpad's Online Platform
• Showpad API, REST Clients, and command lines are no mystery to you

The base endpoint for event calls is:

GET https://{{subdomain}}.showpad.biz/api/v3/exports/events

Every request needs to be prefixed with the base endpoint.

Export JSON

GET https://{{subdomain}}.showpad.biz/api/v3/exports/{{object}}.json

Export CSV

To export in CSV format, change the JSON extension with CSV in your request.

GET https://{{subdomain}}.showpad.biz/api/v3/exports/{{object}}.csv

Note

CSV is only available in the Exports endpoints.

Parameters

Name	Type	Format	Description
channelIds	string		Only include events with the specified channel IDs. You can list multiple IDs by separating them with a comma.
endedAt	string	YYYY-MM-DD | YYYY-MM-DD HH:mm:ss	Only include events that happened before this date.
eventType	string		Only include events with the specified event type. You can list multiple event types by separating them by a comma.
limit	integer	int32	Sets the maximum number of returned items. The maximum limit is set to 1000. For example, if limit is 50, only 50 items will be retrieved.
loggedAfter	string	YYYY-MM-DD | YYYY-MM-DD HH:mm:ss	Only include events that have been logged to Showpad after this date (for offline use, this is when the device comes online).
loggedBefore	string	YYYY-MM-DD | YYYY-MM-DD HH:mm:ss	Only include events that have been logged to Showpad before this date (for offline use, this is when the device comes online).
pageBased	boolean	true | false	Include page-based information in events.
startedAt	string	YYYY-MM-DD | YYYY-MM-DD HH:mm:ss	Only include events that happened after this date.
userId	string		Only include events for a specified user by user ID.

info

For an exhaustive overview of all event types, see Event Types.

Control Returned Items

By default, the maximum number of returned items with the Events call is set to 500. You can use the limit parameter to change this to any value between 50 and 1000.

For larger volumes of data, we include a header in the response, called X-Showpad-Scroll-Id which contains a token. If you make the same request again but set this header on your second request, the events call will return the second batch of requests.

The second reponse will contain another X-Showpad-Scroll-Id header which you can then use to fetch the third batch of requests, and so on. The X-Showpad-Scroll-Id is not changed with every new response but it is valid for a limited time. We recommend always using the scroll id from your most recent response in your next call.

You can loop your requests this way until all data is fetched. Once the response contains no more events, this indicates that no more data can be fetched.

Potential Data Variations

When comparing exports with the reports in the Online Platform, data may differ for several reasons, such as:

	Description
Asset View Data	It's important to understand how the Online Platform calculates reports so that your API exports, which provide the granular data, can be added correctly so you get the same numbers. Example In the Top Content report, shares are calculated as the number of times a piece of content is shared with someone. A document shared with two people at the same time counts as two shares. If the report says 100 shares. This shows which users in the app shared content. That 100 stands for 100 different users.
Details per page	You can export details per page. It's important to be distinguis between events when aggregating the view events on an asset per user as there is an event for every page, and an event for the whole document. For asset analytics, you can obtain the same result as the OP (whole document) by executing the filter where page = NULL.
Deleted records	Users, user groups, assets, etc. can be deleted. OP reporting excludes all events related to users that are deleted and/or inactive. You can obtain identical results by also filtering out these users or groups based on the deletedAt field in the relevant tables.
Date filtering	For date filtering, use the start date of the events.
Divisions	Assets belong to a library (which is a division). Instances can have one or more divisions; Personal files of users are also a division, only accessible by them. There is a division field on events for certain use cases, but it is safest to join divisions with asset tables and not with event tables.
Offline events	Showpad apps track events when offline, and sends data to the server when back online. These events have the original startTime and endTime timestamps as the event timestamp. There is, however, a loggedAt timestamp to detect when the data was received at the server.