What's in for you
To see what you can do with Showpad's API, we share some examples that can inspire and help you build your creation.
Note: Use the API Explorer on Showpad's Online Platform to see a list of all available parameters. You can find it in the API tab of the Admin Settings.
You need this to succeed
- Showpad’s Ultimate pricing plan
- Access to Showpad's Online Platform
- Basic Knowledge of REST
- Basic Knowledge of JSON
- Creating a PDF file with a tag
- Creating an asset link
- Retrieving user information
- Returning an array of users
- Pushing content to a user's personal My Files/My Uploads folder
- Create an asset via the API via Post/assets.json and retrieve the response ID.
- Copy this response ID en go to Tickets.
- Choose: GET/tickets/id.json and fill in the generated ID
- You get a response with the id of the asset:
"asset": { "id": "xxxxx", - Create a tag via POST /tags.json or search tag ID via Get/TAGS.json.
- Copy this tag ID.
- Go to Tags LINK / tags/id.json.
- As ID value, you enter the ID of the tag.
- As Link value, you enter '<add asset ID>; rel="Asset"'
It is possible to get the link to an asset via our public API using the GET ASSET BY ID call:
https://yoursubdomain.showpad.biz/api/v2/assets/0a7c4def949d4da0d461a.json
The response of that call holds the appLink attribute:
{
"meta": {
"code": 200,
"message": "OK",
"serverTime": "2014-06-10 09:19:15",
"lastUpdatedTime": "2014-06-10 09:19:15",
"requestRateLimit": 5000,
"requestRateLimitReset": 86400,
"requestsRemaining": 4987
},
"response": {
"id": "0a7c4def949d4da0d461a842",
"resourcetype": "Asset",
"name": "name.jpg",
"originalName": "orgname.jpg",
"description": null,
"filetype": "photo",
"downloadLink":
"https://yoursubdomain.showpad.biz/api/v2/assets/0a7c4def949d4da0d461a/file",
"previewDownloadLink":
"https://yoursubdomain.showpad.biz/api/v2/assets/0a7c4def949d4da0d461a/preview",
"isSensitive": false,
"isAnnotatable": true,
"isShareable": true,
"fileSize": 364485,
"views": 0,
"averageRating": 0,
"externalId": null,
"createdAt": "2013-07-01 07:32:04",
"updatedAt": "2013-09-05 06:14:50",
"appLink": "showpad://file/02fb913985a38f5ad5ebcf95183792c0",
"tags": {
"href":
"https://yoursubdomain.showpad.biz/api/v2/assets/0a7c4def94d4da0d461a/tags"
},
"division": {
"id": "4643adcc1621814e91c489b34bb428ed",
"href":
"https://yoursubdomain.showpad.biz/api/v2/divisions/4643adcc1681434bb428ed"
}
}
}
These slugs will work as of Showpad on iOS 3.4.2 and Android 1.5.1.
Below is an example of a GET /users/12345.json.
{
"meta": {
"code": 200,
"message": "OK",
"serverTime": "2017-09-30 11:02:39",
"lastUpdatedTime": "2017-09-30 11:02:39",
"requestRateLimit": 5000,
"requestRateLimitReset": 86400,
"requestsRemaining": 4975
},
"response": {
"id": "12345",
"resourcetype": "User",
"firstName": "Nettie",
"lastName": "Pierce",
"email": "nettie@mycompany.com",
"userName": "nettie@mycompany.com",
"language": "en_US",
"userType": "owner",
"apiKey": "someApiKeyWithNumbersAndLetters",
"externalId": null,
"lastLogin": "2017-09-30 10:58:38",
"lastConfirmedContentUpdate": null,
"isActive": true,
"createdAt": "2017-09-29 13:03:31",
"updatedAt": "2017-09-30 10:58:38",
"usergroups": {
"href": "https://my-subdomain.showpad.biz/api/v2/users/12345/usergroups"
},
"tabletpermission": null
}
The response has two distinct parts:
- Meta: contains the response code, the message and the time of the server
- response: contains the actual resource including its ID, type, attributes and relationships
The Showpad API also utilizes the concept of resource links. When a collection of resources is requested (e.g. via GET /users.json), an array of users is returned as shown in the following example:
{
"meta": {
"code": 200,
"message": "OK",
"serverTime": "2017-09-30 11:01:08",
"lastUpdatedTime": "2017-09-30 11:01:08",
"requestRateLimit": 5000,
"requestRateLimitReset": 86400,
"requestsRemaining": 4975
},
"response": {
"count": 2,
"items": [
{
"id": "12345",
"resourcetype": "User",
"href": "https://my-subdomain.showpad.biz/api/v2/users/12345",
"username": "nettie@mycompany.com"
},
{
"id": "123456",
"resourcetype": "User",
"href": "https://my-subdomain.showpad.biz/api/v2/users/123456",
"username": "elsabeth@mycompany.com"
}
]
}
}
The response has 2 distinct parts:
- meta: contains the response code, the message and the time of the server
- response: contains the total count in this collection and an array of resource links. Each resource link contains an ID, a resource type, the location of the resource and some optional attributes. Keep in mind that the count in the reponse is the total count of the results, not the count of the page. For example, if there are 50 users and the limit of this page is 25, the count will be 50 and not 25.
Pushing content to a user's personal My Files folder
You can use the Showpad API to push content into the My Uploads folder of users. The following components are required in order to perform this:
- Add the resourceID of the "My Uploads" division in the response of the GET user/id.json API call.
- Open the POST assets.json API call for admins to be able to post an asset to the personal division id (through the LINK header).
- If the asset already exists (check on filename and extension, in the same division), it will return a 409 HTTP error (conflict). Otherwise, it will return a 201 HTTP error (successful creation).
- Admins are only able to POST to the personal division. They are not able to GET, PUT, DELETE, etc.
- Users can use a POST request to upload to My Files, using:
/divisions/mine/assets.json?postProcessingInstructions={"materialisedPath":"/"}
1. Getting authenticated
POST https://{SUBDOMAIN}.showpad.biz/api/v3/oauth2/token
HTTP Basic Authentication: base64 encode({API_CLIENT_ID}:{{API_CLIENT_SECRET}})
Query Parameters:
- username={USERNAME}
- password={PASSWORD}
- grant_type=password
Response example:
{
"access_token": "c3c7793691bea8e5e4c446260044fa853caec13d-VTJodmQzQmhaRTF2WW1sc1pVTnNhV1Z1ZEE9PS1NakEwTlRJPS1NUT09",
"expires_in": 3600,
"token_type": "bearer",
"scope": "refresh_token read_user_management write_user_management read_contentprofile_management write_contentprofile_management read_division_management write_division_management",
"refresh_token": "388158e65cb215c4757c89c3de1ae95a34609856-VTJodmQzQmhaRTF2WW1sc1pVTnNhV1Z1ZEE9PS1NakEwTlRJPS1NUT09"
}
2. Find the user and the user details
GET https://{SUBDOMAIN}.showpad.biz/api/v3/users.json
Headers: Authorization: Bearer {OAUTH2_TOKEN}
Query Parameters:
- email={USER_EMAILADDRESS}
Response example:
{
"meta":{
"code":200,
"message":"OK",
"serverTime":"2017-09-27T11:49:20+00:00",
"lastUpdatedTime":"2017-09-27T11:49:20+00:00",
"requestRateLimit":5000,
"requestRateLimitReset":86400,
"requestsRemaining":4915
},
"response":{
"count":1,
"items":[{
"id":"322c5a6f89b45933243f3f6281e7f3c2",
"resourcetype":"User",
"href":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/users\/322c5a6f89b45933243f3f6281e7f3c2",
"userName":"promoted.user@showpad.com"
}]
}
}
3. Find the user myUploadsDivisionId
GET https://{SUBDOMAIN}.showpad.biz/api/v3/users/{USER_ID}.json
Headers: Authorization: Bearer {OAUTH2_TOKEN}
Query Parameters:
- fields=myUploadsDivisionId
{
"meta":{
"code":200,
"message":"OK",
"serverTime":"2017-10-02T09:43:06+00:00",
"lastUpdatedTime":"2017-10-02T09:43:06+00:00",
"requestRateLimit":5000,
"requestRateLimitReset":86400,
"requestsRemaining":5000
},
"response":{
"myUploadsDivisionId":"4d3716141c8ffb76928e602548fb9f1c"
}
}
4. Upload the asset and link it correctly
POST https://{SUBDOMAIN}.showpad.biz/api/v3/divisions/{myUploadsDivisionId/}assets.json?postProcessingInstructions={materializedPath: “/”}
Headers: Authorization: Bearer {OAUTH2_TOKEN}
Content-Type: multipart/form-data
Body (example)
--FMhuARzKvs8yEDDv
Content-Disposition: form-data; name="file"; filename="testfile2.txt"
Content-Type: text/plain
fjezjeizfj
--FMhuARzKvs8yEDDv--
{
"meta":{
"code":201,
"message":"Created",
"serverTime":"2017-09-27T11:49:36+00:00",
"lastUpdatedTime":"2017-09-27T11:49:36+00:00",
"requestRateLimit":5000,
"requestRateLimitReset":86400,
"requestsRemaining":4915,
"location":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/assets\/5b65a2743446caa88f62f44b4aad3cc9"},
"response":{
"id":"5b65a2743446caa88f62f44b4aad3cc9",
"resourcetype":"Asset",
"href":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/assets\/5b65a2743446caa88f62f44b4aad3cc9",
"name":"testfile2.txt",
"originalName":"testfile2.txt",
"description":null,
"filetype":"document",
"downloadLink":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/assets\/5b65a2743446caa88f62f44b4aad3cc9\/file\/v1",
"shortLivedDownloadLink":"https:\/\/mycompany.showpad-dev.biz\/share\/1506512976000301\/d7d7f51e598d670c0a21f79291a99d3e61caaef1",
"shortLivedDownloadDuration":30,
"previewDownloadLink":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/assets\/5b65a2743446caa88f62f44b4aad3cc9\/preview\/v1.0",
"thumbnailDownloadLink":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/assets\/5b65a2743446caa88f62f44b4aad3cc9\/thumbnail\/v1.0",
"isSensitive":false,
"isAnnotatable":false,
"isShareable":true,
"isDownloadable":true,
"isDivisionShared":false,
"useOptimized":true,
"fileSize":10,
"views":0,
"externalId":null,
"externalServiceId":null,
"externalDate":null,
"expiresAt":null,
"releasedAt":null,
"createdAt":"2017-09-27T11:49:35+00:00",
"updatedAt":"2017-09-27T11:49:36+00:00",
"archivedAt":null,
"liked":false,
"likesCount":0,
"appLink":"showpad:\/\/file\/32271a3059052a9a5d3310ecfce56d45",
"standardId":"25",
"extension":"txt",
"lockedPages":null,
"pageCount":null,
"isPersonal":true,
"channelTemplateConfigId":null,
"onlyShareEntireDocument":false,
"tags":{
"href":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/assets\/5b65a2743446caa88f62f44b4aad3cc9\/tags"
},
"division":{
"id":"4d3716141c8ffb76928e602548fb9f1c",
"href":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/divisions\/4d3716141c8ffb76928e602548fb9f1c"
},
"assetView":{
"id":"4d4d5b064b589d4ef7c3446f63dcc8a7",
"href":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/assetviews\/4d4d5b064b589d4ef7c3446f63dcc8a7"
},
"uploadedAt":"2017-09-27T11:49:35+00:00"
}
}
Note: When you're uploading an asset that needs processing (e.g. PDF, Word, Excel, Powerpoint, etc), you'll get a Ticket as a response. Keep on polling (every 30 seconds) this ticket resource until you get a valid asset id.
