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
- Retrieving user information
- Returning an array of users
- Pushing content to a user's personal My Files/My Files folder
- Creating assets and tags in the most optimized way
- 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"'
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 Files folder of users. The following components are required in order to perform this:
- Add the resourceID of the "My Files" 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":"/"}&isPersonal=true
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
isPersonal=true
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 ID as a response. Keep on polling (every 30 seconds) this ticket resource until you get a valid Asset ID. More information about file processing is available here.
Creating assets and tags in the most optimized way
Note: In the following scenario, there's no support for divisions.
The quick overview
- Fetch all available tags from Showpad
- Add additional tags — when necessary
- Upload all assets with the required tags
- Check the processing status
The detailed overview
- Fetch all available tags from Showpad.
Fetch all available tags from Showpad and store them in a library or database. This can be a physical database, or just a variable in memory.
It's important that you can easily search for a tag by its name and get its corresponding Showpad ID in return.
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer xxxxxxxxxxxxxxxxxx 'https://subdomain.showpad.biz/api/v3/tags.json?fields=id%2C%20name%2C%20externalService&limit=unlimited'Parameter explanation:
fields=id,name,externalService
This will return just the tag ID, the tag name and the externalService linked to this tag.
When a tag is created via SharePoint, you'll notice the value for externalService is not null.
limit=unlimited
This will return up to 1000 records. Keep an eye on the record count in the response. If it's more than 1000, please add an offset as well for the next request. - Add additional tags — when necessary
curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' --header 'Authorization: Bearer xxxxxxxxxx' -d 'name=API%20tag' 'https://subdomain.showpad.biz/api/v3/tags.json'This will return the Showpad ID for the created tag - Upload all assets with the required tags
This is the big API-call-saver.
curl
X POST --header 'Content-Type: multipart/form-data' --header 'Accept: application/json'-header 'Link: <36613327fa3b3d724211bdbb7c3e6a81;rel=Tag>,<36613327fafb3d724211bdbb7c3e6c91;rel=Tag>' --header 'Authorization: Bearer xxxxxxxxxxxx' 'https://subdomain.showpad.biz/api/v3/assets.json'Note: the actual file upload is omitted from the request above.
Param explanation:
--header Link: this is a comma-separated list of all — in this case — tags that should be linked to the asset. The structure of one Link-item is <showpadId;rel=ResourceType> - Check the processing status
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer xxxxxxxxxx' 'https://subdomain.showpad.biz/api/v3/tickets.json?limit=unlimited&sort=-scheduledAt'Param explanation:
limit=unlimited: This will return up to 1000 records.
sort=-scheduledAt: This will sort the records based on when they were created (scheduled), in a descending order (newest first).
This will make it easier to check which assets got processed (or not).
