The Box View New Developer Hub

Welcome to the Box View New developer hub. You'll find comprehensive guides and documentation to help you start working with Box View New as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Search results for "{{ search.query }}"

No results found for "{{search.query}}".

Overview

 

Note:

We are no longer accepting new sign-ups to the View API and the service will officially EOL on January 15th, 2018. We recently launched a replacement product, New Box View, which has support for additional file types such as video, 360 images, 360 videos and more. You can learn more about New Box View on our developer documentation site.

Existing developers can continue to use View API at this time until the EOL date.

Box View converts PDF and Office documents to HTML thus enabling these files to be easily embedded into web and mobile applications. View a sample document:

Click here to try converting some of your own documents. Getting started is extremely simple:

Example Requests

 

Sample API calls are provided next to each method using cURL, a standard command line tool. All you need to do is drop in your specific parameters, and test the calls from the command line. Here is a great tutorial using cURL with APIs. If the command line isn’t your preference, a great alternative is POSTMAN, an easy-to-use Chrome extension for making HTTP requests.

Input/Output Format

 

All requests must be made with https. Both request body data and response data are formatted as JSON. Every request, including JSON, must have a Content-Type header with a value of application/json. For example:

Content-Type: application/json

Extremely large numbers will be returned in IEEE754 format (the same way doubles are stored in Java). For example: 1.2318237429383e+31

Date Format

 

All timestamps (both those sent in requests and those returned in responses) should be formatted as shown in our examples. Box supports RFC 3339 timestamps. The preferred way to pass in a date is by converting the time to UTC: 2013-04-17T09:12:36-00:00

Rate Limiting

 

In certain cases, Box enforces rate-limiting to prevent abuse by third-party services and/or users. If an excessive usage level is reached, a standard 429 Too Many Requests error will be returned, with an indication of when to retry the request in the form of a Retry-After header with the value in seconds. If back-to-back 429s are issued, we recommend using an exponential backoff algorithm.

HTTP/1.1 429 Too Many Requests
Retry-After: {retry time in seconds}

Authentication

 

The View API uses a standard Authorization header to sign every request. Use a valid API key as the value for the Authorization header:

Authorization: Token YOUR_API_KEY

Supported Filetypes

 

The View API currently supports the following filetypes and MIME types:

Beta Filetypes:

Excel and Text filetypes are currently in beta and conversion quality of these filetypes is not guaranteed.

FILE TYPE
MIME TYPE

.pdf

application/pdf

.doc

application/msword

.docx

application/vnd.openxmlformats-officedocument.wordprocessingml.document

.ppt

application/vnd.ms-powerpoint

.pptx

application/vnd.openxmlformats-officedocument.presentationml.presentation

.xls

application/vnd.ms-excel

xlsx

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

.txt

text/plain

.py

application/x-python

.py

text/x-python

.js

text/javascript

.js

application/x-javascript

.js

application/javascript

.xml

text/xml

.xml

application/xml

.css

text/css

.md

text/x-markdown

.pl

text/x-script.perl

.c

text/x-c

.m

text/x-m

.json

application/json

Document Object

 

Document objects represent files that have been submitted to the View API, and for which an HTML-based preview is generated.

Supported filetypes:

The View API currently supports .pdf, .doc, .docx, .ppt, and .pptx

Attributes

type

document

Type: string

id

A unique string identifying this document.

Type: string

status

An enum indicating the conversion status of this document. Can be queued, processing, done, or error.

Type: string

name

The name of this document.

Type: string

created_at

The time the document was uploaded

Type: timestamp

Example Document

{
  "type": "document",
  "id": "2da6cf9261824fb0a4fe532f94d14625",
  "status": "done",
  "name": "Leaves of Grass",
  "created_at": "2013-08-30T00:17:37Z"
}

/documents

 
get/documents

Query Params

limit
string

The number of documents to return (default=10, max=50).

created_before
date-time

An upper limit on the creation timestamps of documents returned (default=now).

created_after
date-time

A lower limit on the creation timestamps of documents returned.

 

Fetches a list of all documents uploaded using this API Key.

Request

curl https://view-api.box.com/1/documents \
-H "Authorization: Token YOUR_API_KEY"

Results

{
	"document_collection": {
		"total_count": 1,
		"entries": [
			{
        "type": "document",
        "id": "e460608a44c84c02b70a020e7f516de3",
        "status": "done",
        "name": "",
        "created_at": "2013-09-12T19:01:34Z"
			}
		]
	}
}

/documents

URL Upload

 
post/documents

Body Params

url
string
required

The URL of the document to be converted.

name
string

The name of the document.

thumbnails
string

Comma-separated list of thumbnail dimensions of the format {width}x{height} e.g. 128×128,256×256 – width can be between 16 and 1024, height between 16 and 768

non_svg
boolean

Whether to also create the non-svg version of the document (read more here)

 

Upload a new file to the View API for conversion. Files can be uploaded either through a publicly accessible URL or through a multipart POST. In both cases, thumbnail sizes can also be requested for later retrieval. Please see the respective section below for documentation. The list of supported file types can be found here.

non_svg: For supporting users with browsers that don’t support SVG, a second image-based conversion can be created. To request this second conversion, include the non_svg parameter on upload. The viewer will automatically load the correct version based on the user’s browser.

URL Upload

Use this upload method when you have a publicly accessible URL to the document that you want to convert

Request

curl https://view-api.box.com/1/documents \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "http://www.example.com/MyFile.pdf"}' \
-X POST

Results

{
  "type": "document",
  "id": "2da6cf9261824fb0a4fe532f94d14625",
  "status": "done",
  "name": "",
  "created_at": "2013-08-30T00:17:37Z"
}

/documents

Multipart Upload

 
post/documents

Body Params

file
file
required

The contents of the file

name
string

The name of the document.

thumbnails
string

Comma-separated list of thumbnail dimensions of the format {width}x{height} e.g. 128×128,256×256 – width can be between 16 and 1024, height between 16 and 768

non_svg
boolean

Whether to also create the non-svg version of the document (read more here)

 

Multipart Upload

Use this upload method when you have the actual file contents of the document you want to convert. Uploads are handled through a special base URL: https://upload.view-api.box.com.

Upload URL: Multipart uploads are handled through https://upload.view-api.box.com.

Request

curl https://upload.view-api.box.com/1/documents \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-type: multipart/form-data" \
-F file=@A_FILE_TO_UPLOAD

Results

{
  "type": "document",
  "id": "2da6cf9261824fb0a4fe532f94d14625",
  "status": "processing",
  "name": "",
  "created_at": "2013-08-30T00:17:37Z"
}

/documents/{id}

 
get/documents/id

Query Params

fields
string
required

Comma-separated list of fields to return. id and type are always returned.

 

Retrieves the metadata for a single document.

Request

curl https://view-api.box.com/1/documents/DOCUMENT_ID \
-H "Authorization: Token YOUR_API_KEY"

Results

{
  "type": "document",
  "id": "2da6cf9261824fb0a4fe532f94d14625",
  "status": "done",
  "name": "Leaves of Grass",
  "created_at": "2013-08-30T00:17:37Z"
}

/documents/{id}/content.{extension}

 
get/documents/id/content.extension
 

Fetches a document in the form specified by extension, which can be one of pdf, zip, or txt . If an extension is not specified, the document’s original format is returned. The zip file will contain the converted HTML and SVG assets, and optionally the PNG assets if the non_svg parameter was specified on upload. For displaying the converted assets contained in the zip version, please see the documentation for viewer.js.

Request

curl https://view-api.box.com/1/documents/DOCUMENT_ID/content.zip \
-H "Authorization: Token YOUR_API_KEY"

Results

{a .zip representation of the document}

/documents/{id}/thumbnail

 
get/documents/id/thumbnail

Query Params

width
int32
required

The width of the thumbnail in pixels, between 16 and 1024

height
int32
required

The height of the thumbnail in pixels, between 16 and 768

 

Retrieve a thumbnail image of the first page of a document. Thumbnails can have a width between 16 and 1024 pixels and a height between 16 and 768 pixels. Thumbnails can be requested in the upload request of a document to make them available more quickly.

Aspect Ratio: Thumbnails will always preserve the aspect ratio of the original document but will best fit the dimensions requested. For example, if a 16×16 thumbnail is requested for a document with a 2:1 aspect ratio, a 16×8 thumbnail will be returned.

Possible HTTP Status Codes

200

200 The thumbnail is returned

202

The thumbnail isn’t available yet. A Retry-After header will be included in the response indicating the time to wait before trying again

400

width or height parameters are invalid

Request

curl https://view-api.box.com/1/documents/DOCUMENT_ID/thumbnail?width=16&height=16 \
-H "Authorization: Token YOUR_API_KEY"

Results

{an image representation of the file}
{
  "message": "Bad request",
  "type": "error",
  "details": [{
                "field": "width",
                "message": "Ensure this value is less than or equal to 1024."
                }],
  "request_id": "e8c3624459e44815a2ee6c82b953de24"
}

/documents/{id}

 
put/documents/id

Body Params

name
string

The name of the document.

 

Updates the metadata of a specific document.

Request

curl https://view-api.box.com/1/documents/DOCUMENT_ID \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "A New Name"}' \
-X PUT

Results

{
  "type": "document",
  "id": "2da6cf9261824fb0a4fe532f94d14625",
  "status": "done",
  "name": "A New Name",
  "created_at": "2013-08-30T00:17:37Z"
}

/documents/{id}

 
delete/documents/id
 

Removes a document completely from the View API servers. This action cannot be undone.

Request

curl https://view-api.box.com/1/documents/DOCUMENT_ID \
-H "Authorization: Token YOUR_API_KEY" \
-X DELETE

Results

Session Object

 

Sessions are used whenever an end-user needs to view, download, or otherwise interact with a document. This is done so that end-users can interact with Box View documents without the API client needing to expose an API Key to the end-user. Sessions are generally short-lived and by default expire in one hour. Sessions can only be created for documents that have a status of done or after the document.viewable webhook notification is sent. See webhooks for more information.

Session Object

Attributes

id

A unique string identifying this session.

Type: string

type

session

Type: string

expires_at

The time when this session will expire

Type: timestamp

urls

URLs for use with viewer.js provided as a convenience

Type: object

Example Session

{
    'type': 'session',
    'id': '4fba9eda0dd745d491ad0b98e224aa25',
    'expires_at': '3915-10-29T01:31:48.677Z',
    'urls': {
        'view': 'https://view-	api.box.com/1/sessions/4fba9eda0dd745d491ad0b98e224aa25/view',
        'assets': 'https://view-api.box.com/1/sessions/4fba9eda0dd745d491ad0b98e224aa25/assets/',
        'realtime': 'https://view-api.box.com/sse/4fba9eda0dd745d491ad0b98e224aa25'
    }
}

/sessions

 
post/sessions

Body Params

document_id
string
required

The ID of the document for which to create a session.

duration
int32

The duration in minutes until the session expires.

expires_at
date-time

The timestamp at which the session should expire.

is_downloadable
boolean

Whether a button will be shown allowing the user to download the original file. The original file will also be accessible via GET /sessions/{id}/content while the session is valid

is_text_selectable
boolean

Whether text in the document will be selectable by the end user. This parameter will only affect the embedded iframe viewer. To disable text selection using viewer.js, use the enableTextSelection parameter

 

Creates a session for a single document. Sessions can only be created for documents that have a status of done or after the document.viewable webhook notification is sent.

Alert: For an individual request, you can either use duration or expires_at.

Possible HTTP Status Codes

201

The session was successfully created.

202

The document is not ready for viewing. A Retry-After header will be included in the response indicating the time to wait before trying again.

400

An error occurred while converting the document, or the document does not exist.

Request

curl https://view-api.box.com/1/sessions \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"document_id": "ABC123"}' \
-X POST

Results

{
    'type': 'session',
    'id': '4fba9eda0dd745d491ad0b98e224aa25',
    'expires_at': '3915-10-29T01:31:48.677Z',
    'urls': {
        'view': 'https://view-api.box.com/1/sessions/4fba9eda0dd745d491ad0b98e224aa25/view',
        'assets': 'https://view-api.box.com/1/sessions/4fba9eda0dd745d491ad0b98e224aa25/assets/',
        'realtime': 'https://view-api.box.com/sse/4fba9eda0dd745d491ad0b98e224aa25'
    }
}
{
  "message": "Bad request",
  "type": "error",
  "details": 
  	[{
    	"field": "document_id",
   	"message": "The specified document is not viewable since an error occurred when converting it"
 	}]
}

/sessions/{id}

 
delete/sessions/id
 

Removes a session completely from the View API servers. This action cannot be undone.

Request

curl https://view-api.box.com/1/sessions/SESSION_ID \
-H "Authorization: Token YOUR_API_KEY" \
-X DELETE

Use a Session with viewer.js

 

The URL to view a document in viewer.js can be found in a successful session response under urls.assets. Please click here for more information about viewer.js.

Loading this URL with viewer.js would look like:

var viewer = Crocodoc.createViewer('.viewer', {
url: '{ASSETS_URL}'
});
viewer.load();
 

View a Document

 

To view a document first create a session. The URL to view a document with a generated session can be found in a successful session response under urls.view.

You can change the theme of the viewer by appending a query parameter to the view url like so:

https://view-api.box.com/1/sessions/45413be2a4b04f9b963770917e651532/view?theme={theme style}

The currently supported themes are light and dark. White looks best with documents that contain any sort of media, while black looks best with text-heavy, black and white documents (e.g. academic papers). These URLs are suitable for use as a top-level window or within an iframe. The viewer has controls that utilize the native fullscreen functionality in browsers, so this is the recommended embed code:

<iframe src="https://view-api.box.com/1/sessions/45413be2a4b04f9b963770917e651532/view?theme=dark" style="width: 640px; height: 500px; border-radius: 5px; border: 1px solid #d9d9d9;"  allowfullscreen="allowfullscreen"></iframe>

/settings/storage-profile

 
post/settings/storage-profile

Body Params

provider
string

Only S3 is currently supported

s3_bucket_name
string

Name for your bucket

s3_access_key_id
string

Access key

s3_secret_access_key
string

Secret access key

 

Creates a custom storage profile on S3 to store documents. Validates that the supplied access credentials have all required authorizations on the specified bucket.

Request

curl https://view-api.box.com/1/settings/storage-profile \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"provider": "S3", "s3_bucket_name": "super-awesome-bucket", "s3_access_key_id": "AKIAIOSFODNN7EXAMPLE", "s3_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY"}' \
-X POST

Results

{
    "provider": "S3",
    "s3_bucket_name": "super-awesome-bucket",
    "s3_access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "s3_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY"
}

/settings/storage-profile

 
get/settings/storage-profile
 

Shows the current storage profile configuration

Request

curl https://view-api.box.com/1/settings/storage-profile \
-H "Authorization: Token YOUR_API_KEY"

Results

{ 
    "provider": "S3",
    "s3_bucket_name": "super-awesome-bucket",
    "s3_access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "s3_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY"
}

/settings/storage-profile

 
delete/settings/storage-profile
 

Reverts a user back to the default View API managed storage profile. Note that following a DELETE requests, only future uploaded documents will be stored in default View API storage; existing documents are NOT transferred out of the custom bucket.

Request

curl https://view-api.box.com/1/settings/storage-profile \
-H "Authorization: Token YOUR_API_KEY" \
-X DELETE

Results

/settings/webhook

 
post/settings/webhook

Body Params

url
string

URL to receive callbacks

 

Sets up a webhook url to receive notifications from the View API service. Sends a sample webhook payload to the specified URL to validate it is reachable and that it returns a successful (i.e. 2xx) HTTP status code.

Request

curl https://view-api.box.com/1/settings/webhook \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://wow.such.io/view-api-callback"}' \
-X POST

Results

{
 "url": "https://wow.such.io/view-api-callback"
}

/settings/webhook

 
get/settings/webhook
 

Gets the webhook url that has been set.

Request

curl https://view-api.box.com/1/settings/webhook \
-H "Authorization: Token YOUR_API_KEY" \

Results

{
 "url": "https://wow.such.io/view-api-callback"
}

/settings/webhook

 
delete/settings/webhook
 

Deletes the webhook url. No more notifications will be sent after the url is deleted.

Request

curl https://view-api.box.com/1/settings/settings \
-H "Authorization: Token YOUR_API_KEY" \
-X DELETE

Results