Introduction
Welcome to Documill View API. The basic workflow is simple:
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 | |
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:
- 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.
- 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:
- data-profile: Name of the custom profile to use
- data-theme: Name of the custom theme to use
- data-profile-settingName: Value for the profile setting settingName. Overrides the other values for this setting.
- data-theme-settingName: Value for the theme setting settingName. Overrides the other values for this setting.
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:
DocumillViewEmbed.openOverlay(configuration)
DocumillViewEmbed.openFloating(configuration)
DocumillViewEmbed.openExternal(configuration)
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:
- POSTing a named profile using the API
- Using the theme either by appending
&profile=customProfile
to the viewer URL, or by usingdata-profile=customProfile
if using the embed.js library.
Configurable properties include:
homeURL
: The URL that the viewer logo points to.openedPage
: Page number the viewer opens at, first page being1
. Numbers beyond document’s total page count default to last page.output
: Eitherhtml
orimg
. Valuestext
andthumbnails
are also supported.thumbnailsShown
: If thumbnails are shown.ribbon
: Show Ribbon controls instead of default viewer controls. Using embed.js is recommended instead of using this parameter directly.initialLayout
: One of:normal
: Normal viewer layouttwoPages
: Two pages side-by-sideposter
: Grid layout, as many pages as fit the window side-by-side.horizontal
: Horizontal layout, for usage with Ribbon controls. Using embed.js is recommended instead of using this parameter directly.
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:
- POSTing a named theme using the API
- Using the theme either by appending
&theme=customTheme
to the viewer URL, or by usingdata-theme=customTheme
if using the embed.js library.
The following details can be customized:
- Logo and favicon
- Font used in the viewer (user interface only, not the document contents)
- Top bar and viewer area colors (e.g. page border color, viewer background color)
- Button colors and visibility (e.g. top bar buttons)
- Alternative button colors (e.g. thumbnail open/close button, ribbon left/right buttons)
- Visibility and colors of page number overlays
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:
- Logo and favicon: URL starting with
http://
orhttps://
, or base64 encoded GIF image starting withdata:image/gif;base64,
. - Font: CSS font-family notation, e.g.
"Courier New", Courier, monospace
- Colors: Common CSS color notations, e.g.
white
,rgba(255,255,255,1)
,#FFFFFF
- Visibility:
visible
orhidden
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:
- Using a viewer URL: Append
&profileOverrides={...}
to the URL, e.g.&profileOverrides={openedPage: 10}
- Using embed.js: Add the attribute
data-profile-...="..."
to the embedding element, e.g.data-profile-openedPage="10"
To override a theme property:
- Using a viewer URL: Append
&themeOverrides={...}
to the URL, e.g.&themeOverrides={viewerBackgroundColor: "darkgray"}
- Using embed.js: Add the attribute
data-theme-...="..."
to the embedding element, e.g.data-theme-viewerBackgroundColor="darkgray"
Note that the property values should be properly encoded so that they are transmitted correctly:
- To encode URL parameters in Javascript, use
encodeURIComponent
andJSON.stringify
- To encode an HTML attribute in Javascript, use
element.setAttribute(...)
which automatically handles encoding.
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:
document.posted
: the document has been posteddocument.processingStarted
: the transformation of the document has started but no results are ready yetdocument.firstPageReady
: the results of the first page are readydocument.ready
: the transformation has ended successfully and all the results are readydocument.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.