NAV

Introduction

Welcome to Documill View API. The basic workflow is simple:

  1. Post a document
  2. Get document status
  3. Create a viewing session for the document
  4. Open a viewer

In the following sections we will guide you through this process.

Authorization

To authorize with e.g. curl

curl \
  -H "Accept: application/json" \
  -H "Authorization: $API_KEY" \
  https://view-api.documill.com/api/v0/document

Make sure to replace $API_KEY with your own API key.

If you have not processed any documents, the expected response for the above API call is an empty list.

A valid API key is needed to access the API. You can get your own API key from us.

When using the API, you need to supply your API key as the value of the Authorization header.

Supported document types

The Documill View API supports the following document types:

MIME TYPE FILE TYPE(S)
application/msword .doc
application/vnd.openxmlformats-officedocument.wordprocessingml.document .docx
application/vnd.openxmlformats-officedocument.wordprocessingml.template .dotx
application/vnd.ms-pps application/mspowerpoint .ppt, .pps, .pot, .ppa
application/vnd.openxmlformats-officedocument.presentationml.template .potx
application/vnd.openxmlformats-officedocument.presentationml.presentation .pptx
application/vnd.openxmlformats-officedocument.presentationml.slideshow .ppsx
application/vnd.ms-excel .xls
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet .xlsx
application/pdf .pdf
application/rtf .rtf

Basic usage

1. Post document

Replace the $API_KEY variable with your API key

Also replace the $DOCUMENT_URL with a document’s URL. An example document: example.pdf.

Note that if the $DOCUMENT_URL contains special characters, it should be properly URL-escaped with e.g. Javascript’s encodeURIComponent

curl -X POST \
  -H "Accept: application/json" \
  -H "Authorization: $API_KEY" \
  "https://view-api.documill.com/api/v0/document?url=$DOCUMENT_URL"

Example response

{
  "id": "123456789",
  "name": "Example",
  "status": "processing",
  "pageCount": 0,
  "createdAt": "2015-10-05T12:34:56.789+03:00",
  "originalURL": "http://example.com/example.pdf",
  "downloadFilename": "example.pdf",
  "originalDocumentSaved": true,
  "viewable": false
}

The primary resources that this API deals with are documents.

Documents are represented as JSON objects and identified by their id.

Posting a new document involves one HTTP POST request to the API method /document.

Note the documents id, you will need it when creating a viewing session. You can also upload a document file directly, see API reference for details.

See API reference documentation for more information about possible query parameters.

2. Get document status

curl -X GET \
  -H "Accept: application/json" \
  -H "Authorization: $API_KEY" \
  "https://view-api.documill.com/api/v0/document/$DOCUMENT_ID"

Example response

{
  "id": "123456789",
  "name": "Example",
  "status": "processing",
  "pageCount": 1,
  "createdAt": "2015-10-05T12:34:56.789+03:00",
  "originalURL": "http://example.com/example.pdf",
  "downloadFilename": "example.pdf",
  "originalDocumentSaved": true,
  "viewable": true
}

Documents can only be viewed after their viewable property is true. This normally happens after the document has been succesfully downloaded and the first page of the document has been processed.

To get the status of the document, make a GET request to /document. This information can also be received by using webhooks.

When the returned document’s viewable property is true, proceed to next step. If the document status is failed, there has been a problem, and you need to re-check that the URL is publicly accessible and that the file behind that URL is a valid document file.

3. Create viewing session

Create session

curl -X POST \
  -H "Accept: application/json" \
  -H "Authorization: $API_KEY" \
  "https://view-api.documill.com/api/v0/session?documentId=$DOCUMENT_ID&duration=60"

Example response

{
  "id": "12345-6789a-bcdef",
  "expiresAt": "2015-10-06T18:13:38.788+03:00",
  "viewerURL": "https://viewer.documill.com/viewer/view?sessionId=12345-6789a-bcdef"
}

To view the document, a viewing session is required. A viewing session is a temporary view access grant to a document with a non-guessable session id.

To create a viewing session that is valid for 60 minutes, make a POST request to /session.

The session’s session id is randomly generated, and the viewerURL will only work until the time in expiresAt.

To create a viewing session with custom duration, you can supply the desired duration in minutes as a query parameter to /session

4. Open viewer

To view the document, navigate with your browser to the viewerURL received in the created session object in the previous step.

Embedding viewer

These instructions cover how to embed the viewer on a web page. You will need a valid document session id received at Create viewing session.

There are two categories and a total of five types of viewers supported by the embedding library:

  1. Embedded viewers
    • Embedded: Viewer inside a container element on a HTML page.
    • Ribbon: Horizontal page previews that can be clicked to open a larger viewer.
  2. Openable/closable viewers
    • Overlay: Covers the current page.
    • Floating: Opens on top of the current page, allowing the user to interact with the current page while viewing the document.
    • External: Opens in a new tab or a window

Configuration of the embedded viewers is done via HTML5 data attributes.

1. Include embed.js

First you need to include the embed.js javascript library on the web page that embeds the viewer.

<html>
  <head>

    <script src="https://viewer.documill.com/viewer/public/embed.js"></script>

  </head>
  ...

The embed.js library is located at https://viewer.documill.com/viewer/public/embed.js.

2. Embed the viewer

The simplest way to embed a viewer is to add a DIV element with either of the classes documill-view-viewer-embedded or documill-view-viewer-ribbon. Additionally, the session ID received at Create viewing session should be set via the attribute data-session-id.

Embedded viewer

<h2>Embedded viewer</h2>

<div
  class="documill-view-viewer-embedded"
  style="position: relative; width: 30em; height: 20em; border: 1px solid #dddddd;"
  data-session-id="$DOCUMENT_SESSION_ID"
  >
</div>

The documill-view-viewer-embedded class instructs embed.js to embed a viewer inside the DIV. The viewer will size itself to fit its container.

Ribbon viewer

<h2>Ribbon viewer</h2>

<div
  class="documill-view-viewer-ribbon"
  style="position: relative; width: 50em; height: 10em; border: 1px solid #dddddd;"
  data-session-id="$DOCUMENT_SESSION_ID"
  >
</div>

The documill-view-viewer-ribbon class embeds a horizontal document page preview viewer. This variant shows smaller previews of document pages, which can be clicked to open a larger overlay viewer.

3. Viewer buttons

<h2>Viewer buttons</h2>

<div>
  <a class="documill-view-viewer-overlay" data-session-id="$DOCUMENT_SESSION_ID">Overlay</a>
  <a class="documill-view-viewer-floating" data-session-id="$DOCUMENT_SESSION_ID">Floating</a>
  <a class="documill-view-viewer-external" data-session-id="$DOCUMENT_SESSION_ID">External</a>
</div>

To make an element a clickable button that opens a viewer, add one of the classes documill-view-viewer-overlay, documill-view-viewer-floating or documill-view-viewer-external to the element.

These buttons can be created and removed at any time, including dynamically via javascript.

4. Customize the embedded viewer

The viewer buttons and embedded viewer DIV borders and positioning can be freely styled to fit the embedding page. This can be done either via inline styles like in the examples, or by adding one or more CSS classes, just like ordinary HTML elements.

<h2>Customized viewer</h2>

<div
  class="documill-view-viewer-embedded"
  style="position: relative; width: 50em; height: 30em; border: 1px solid #dddddd;"
  data-session-id="$DOCUMENT_SESSION_ID"
  data-theme="customTheme"
  data-theme-viewerBackgroundColor="darkgray"
  data-theme-topbarBackgroundColor="lightgray"
  data-profile="customProfile"
  data-profile-thumbnailsShown="true"
  >
</div>

Controlling the look and behaviour of the viewer itself can be done via viewer themes and profiles. The theme and profile and overrides to settings in them can be specified using one or multiple of the following data attributes:

For more information on profiles and themes and the available settings, see the section Viewer Customization and the related API documentation.

5. Using viewer via Javascript

Embedding via Javascript

Embed a viewer dynamically with Javascript.

var sessionId = "$DOCUMENT_SESSION_ID";

var viewerDiv = document.createElement("div");
viewerDiv.setAttribute("data-session-id",sessionId);
viewerDiv.setAttribute("class","documill-view-viewer-embedded");
viewerDiv.style.width = "30em";
viewerDiv.style.height = "20em";
document.body.appendChild(viewerDiv);

Both embedded and ribbon viewer DIVs can be created and removed at any time, including dynamically via Javascript.

Opening a viewer via Javascript

Open a floating viewer via Javascript

var configuration = {
  sessionId: "$DOCUMENT_SESSION_ID",
  profile: "customProfile",
  profileOverrides: {openedPage: 10, thumbnailsShown: false},
  theme: "customTheme",
  themeOverrides: {viewerBackgroundColor: "darkgray"}
}

DocumillViewEmbed.openFloating(configuration);

To open an overlay, floating or external viewer via Javascript, call one of the following methods:

Where configuration is a javascript object of format

javascript { sessionId: string, profile: string, profileOverrides: object, theme: string, themeOverrides: object }

Only the sessionId parameter is mandatory, others are optional.

For more information on profiles and themes and the available settings, see the section Viewer Customization and the related API documentation.

Viewer customization

1. Viewer profiles

A viewer profile is a named collection of settings that controls which user interface elements are shown and how they behave in the viewer.

To post a profile named ‘customProfile’:

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: $API_KEY" -d "{
  \"thumbnailsShown\": false,
  \"initialLayout\": \"poster\"
}" "https://view-api.documill.com/api/v0/settings/viewer/profile/customProfile"

# After this, direct your browser to
# https://viewer.documill.com/viewer/view?sessionId=$DOCUMENT_SESSION_ID&profile=customProfile

Example response

{"message":"Ok."}

Basic profile configuration involves:

Configurable properties include:

See the profile API for the API documentation.

2. Viewer themes

Viewer themes affect the visual appearance of the viewer.

To post a theme named 'customTheme’:

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: $API_KEY" -d "{
  \"logo\": \"https://platform.documill.com/tutorial-view/tutorial/../examples/logo.png\",
  \"favicon\": \"https://platform.documill.com/tutorial-view/tutorial/../examples/favicon.png\",
  \"buttonColor\": \"#008000\",
  \"viewerBackgroundColor\": \"rgba(123,123,123,0.5)\"
}" "https://view-api.documill.com/api/v0/settings/viewer/theme/customTheme"

# After this, direct your browser to
# https://viewer.documill.com/viewer/view?sessionId=$DOCUMENT_SESSION_ID&theme=customTheme

Example response

{"message":"Ok."}

Basic theme configuration involves:

The following details can be customized:

All theme properties are optional. If a property is unspecified, its value will be the default value of the default viewer theme.

Each property (except logo and favicon) corresponds to a CSS property and possibly a state. For example, buttonHoverBackgroundColor: "gray" means the same as CSS structured like .button:hover { background-color: gray; }.

Supported values include:

See the theme API for a comprehensive list of supported theme parameters.

3. Dynamically specifying properties

If more flexibility is desired, a property value can be overridden when opening or embedding a viewer.

Opening a viewer at page 10:

var viewerURL = "https://viewer.documill.com/viewer/view?sessionId=$DOCUMENT_SESSION_ID"

var profileOverrides = {openedPage: 10};

viewerURL += "&profileOverrides="+encodeURIComponent(JSON.stringify(profileOverrides));

window.open(viewerURL);

Embedding a viewer that opens at page 10:

var sessionId = "$DOCUMENT_SESSION_ID";

var viewerDiv = document.createElement("div");
viewerDiv.setAttribute("data-session-id",sessionId);
viewerDiv.style.width = "30em";
viewerDiv.style.height = "20em";
viewerDiv.setAttribute("class","documill-view-viewer-embedded");

viewerDiv.setAttribute("data-profile-openedPage","10");

document.body.appendChild(viewerDiv)

To override a profile property:

To override a theme property:

Note that the property values should be properly encoded so that they are transmitted correctly:

Advanced topics

Embedding viewer without using embed.js

The recommended way to embed a viewer is by using embed.js. If this is not possible due to e.g. a security policy, the viewer can be embedded directly.

To embed the viewer without using embed.js, simply use an iframe with src pointing to the viewer URL.

A viewer embedded this way can be customized using the profile and theme URL parameters. See Viewer Customization for more information on customization.

Using webhooks

Example webhook notification data

[
  {
    "type": "document.posted",
    "data": {
      "id": "1"
    },
    "triggered_at": "2015-12-02T12:34:56.789Z"
  },
  {
    "type": "document.failed",
    "data": {
      "id": "2",
      "message": "Processing failed."
    },
    "triggered_at": "2015-12-02T12:34:56.789Z"
  },
  {
    "type": "document.processingStarted",
    "data": {
      "id": "3"
    },
    "triggered_at": "2015-12-02T12:34:56.789Z"
  },
  {
    "type": "document.firstPageReady",
    "data": {
      "id": "4"
    },
    "triggered_at": "2015-12-02T12:34:56.789Z"
  },
  {
    "type": "document.ready",
    "data": {
      "id": "5"
    },
    "triggered_at": "2015-12-02T12:34:56.789Z"
  }
]

The API methods /document and /document/upload have an optional parameter webhookURL that you can use to specify a URL to receive webhook notifications about the progress of the document. The notifications are sent as JSON array of event objects by a HTTP POST request to the specified URL. Note that the event objects may refer to different documents if the same 'webhookURL’ value is used with multiple documents.

The following event types are supported:

  1. document.posted: the document has been posted
  2. document.processingStarted: the transformation of the document has started but no results are ready yet
  3. document.firstPageReady: the results of the first page are ready
  4. document.ready: the transformation has ended successfully and all the results are ready
  5. document.failed: the document could not be processed for some reason, e.g. the document URL may have been mistyped, or it may refer to a resource that isn’t a supported document type

All of the above event types have a nested data object, whose id property is the id of the relevant document.

Further details

To get more details about the supported methods and their parameters, see the API reference documentation.