Examples

  • Updated
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

Recipes to get you started

Creating a PDF with a tag

  1. Create an asset via the API via Post/assets.json and retrieve the response ID.
  2. Copy this response ID en go to Tickets.
  3. Choose: GET/tickets/id.json and fill in the generated ID
  4. You get a response with the id of the asset:
    "asset": { "id": "xxxxx",
  5. Create a tag via POST /tags.json or search tag ID via Get/TAGS.json.
  6. Copy this tag ID.
  7. Go to Tags LINK / tags/id.json.
  8. As ID value, you enter the ID of the tag.
  9. As Link value, you enter '<add asset ID>; rel="Asset"'
Back to the menu

Creating an asset link

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.

Back to the menu

Retrieving user information

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
Back to the menu

Returning an array of users

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. 
Back to the menu

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.
  • Only Admins and Owners can push to My Uploads.
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 myUploadsId 
GET https://{SUBDOMAIN}.showpad.biz/api/v3/users/{USER_ID}.json

Headers: Authorization: Bearer {OAUTH2_TOKEN}

Query Parameters:

  • fields=myUploadsCollectionId
{
    "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":{
        "myUploadsCollectionId":"4d3716141c8ffb76928e602548fb9f1c"
    }
}
4. Get the "My Uploads" target

GET https://{SUBDOMAIN}.showpad.biz/api/v3/users/{USER_ID}.channels.json

Headers: Authorization: Bearer {OAUTH2_TOKEN}

Query Parameters:

  • name=My Channel
  • personalContentIncluded=true
{
    "meta":{
        "code":200,
        "message":"OK",
        "serverTime":"2017-09-27T11:49:26+00:00",
        "lastUpdatedTime":"2017-09-27T11:49:26+00:00",
        "requestRateLimit":5000,
        "requestRateLimitReset":86400,
        "requestsRemaining":4915
    },
    "response":{
        "count":1,
        "items":[{
            "id":"ccb1c4358635cb7706590350818f9cfa",
            "resourcetype":"Channel",
            "href":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/channels\/ccb1c4358635cb7706590350818f9cfa",
            "name":"My Channel"
        }]
    }
}

Note: The result of this call can be empty. In that case, execute the next call.

POST https://{SUBDOMAIN}.showpad.biz/api/v3/channelnodes/{userId}/root/children.json

Headers: Authorization: Bearer {OAUTH2_TOKEN}

Post body: {} 

Recall the following:

GET https://{SUBDOMAIN}.showpad.biz/api/v3/users/{USER_ID}.channels.json
5. Upload the asset and link it correctly 
POST https://{SUBDOMAIN}.showpad.biz/api/v3/divisions/{myUploadsDivisionId/}assets.json

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.

6. Get the root node for the "My Uploads" channel 
GET https://{SUBDOMAIN}.showpad.biz/api/v3/channels/{result from Get the "My Uploads" target}

Headers: Authorization: Bearer {OAUTH2_TOKEN}

Query Parameters:

  • fields=rootChannelNode
{
    "meta":{
        "code":200,
        "message":"OK",
        "serverTime":"2017-09-27T11:49:39+00:00",
        "lastUpdatedTime":"2017-09-27T11:49:39+00:00",
        "requestRateLimit":5000,
        "requestRateLimitReset":86400,
        "requestsRemaining":4915
    },
    "response":{
        "rootChannelNode":{
            "id":"cf40863abe2247c6dd5b0618ff10692385dc131c80bd5ec218a77340eaa59943",
            "href":"https:\/\/mycompany.showpad-dev.biz\/api\/v3\/channelnodes\/cf40863abe2247c6dd5b0618ff10692385dc131c80bd5ec218a77340eaa59943"
        }
    }
}
LINK https://{SUBDOMAIN}.showpad.biz/api/v3/channelnodes/{ROOT_CHANNEL_NODE}/assets/{ASSET_ID}

Headers: Authorization: Bearer {OAUTH2_TOKEN}

{
    "meta":{
        "code":200,
        "message":"OK",
        "serverTime":"2017-09-27T11:49:42+00:00",
        "lastUpdatedTime":"2017-09-27T11:49:42+00:00",
        "requestRateLimit":5000,
        "requestRateLimitReset":86400,
        "requestsRemaining":4915
    }
}

Related articles

Get the latest apps and email integrations

iOS App Store Google Play Store Microsoft Store