Box Developer Platform

Viewing Your First Document

Note:

We are no longer accepting new sign ups to the View API. New developers can use this endpoint in Content API to leverage Box's Preview services. Existing developers can continue to use View API at this time.

If you are currently building with the View API, please use the View API Reference Docs.

1. Upload a Document

First, upload a document to the View API. You’ll need a URL to a valid document type. If you don’t have a URL to a document readily available, you can use this URL: https://cloud.box.com/shared/static/zzxlzc38hq7u1u5jdteu.pdf. Note that if you want to use a link from Box, it must be Open Access and a direct link e.g.

curl https://view-api.box.com/1/documents \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://cloud.box.com/shared/static/4qhegqxubg8ox0uj5ys8.pdf"}' \
-X POST

Replace YOUR_API_KEY with the API Key you created earlier.

The response will look like this:

{
    "type": "document",
    "id": "THE_DOCUMENT_ID",
    "status": "queued",
    "name": "",
    "created_at": "2013-08-30T00:17:37Z",
    "modified_at": "2013-08-30T00:17:37Z"
}

Make a note of the unique document ID THE_DOCUMENT_ID for the next step.

2. Create a Session

Using the unique document ID from the previous step, create a session for this document. We’ll set the duration to 60 minutes, making the session expire in one hour. This time, we’ll use curl’s -i flag to see the response headers and status code (you’ll see why in a moment).

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

If all goes well and the document has been converted, you’ll see a 201 response like this:

HTTP/1.1 201 CREATED
Server: nginx
Date: Fri, 27 Dec 2013 01:55:40 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept
X-Frame-Options: SAMEORIGIN
Allow: POST, OPTIONS
{
    "type": "session",
    "id": "e3f0b2187eb4402a86ed07870420b5b8",
    "expires_at": "2013-12-27T02:55:40.149Z"
}

However, if the document is not ready yet, you’ll receive a 202 response like this:

HTTP/1.1 202 ACCEPTED
Server: nginx
Date: Fri, 27 Dec 2013 02:00:35 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Retry-After: 2
Vary: Accept
X-Frame-Options: SAMEORIGIN
Allow: POST, OPTIONS

This means that the document is still converting. The value of the Retry-After indicates the number of seconds you should wait before trying the request again.

3. View the Document

To view the converted document, you just need to go directly to the Session URL in your browser using the id of the session from the last step:

https://view-api.box.com/1/sessions/{session_id}/view?theme=light 

where {session_id} is the unique session ID from the previous step. Embedding the session is as simple as including this URL as an iframe in a webpage, i.e. something like this snippet:

<iframe src="SESSION_URL" seamless fullscreen></iframe>

Your end result will look like this (with your document, of course):

Viewing Your First Document