Announcing General Availability of Web Annotations for Box Platform

Today, we are excited to announce that annotations are now generally available for Box Platform. Annotations help you bring a whole new level of collaboration to your apps by allowing your users to highlight text in files and add comments to specific parts of a file preview, such as a particular slide in a presentation. We announced the public beta for annotations earlier this summer and dozens of companies participated, using annotations for use cases ranging from marking up loan documents to highlighting in candidate resumes.

Available at no additional cost via the Box API for web browsers, annotations are enabled for documents, presentation, and image file types. You can start using annotations in your custom app today. Annotations are available by simply adding a query parameter to an embeddable file URL obtained via the Get Embed Link of the Box Content API.

Annotations enable a different type of collaboration in your apps from traditional comments. For example, a financial advisor could highlight a particular paragraph in a contract for a client to review in a client portal, or a project manager can add a comment to a specific area of a construction floor plan, easily viewed in a mobile app for construction workers. Annotations are unique in that they are added to the file rendering itself, as opposed to a comment sidebar, and enable in-file edits and mark up in addition to conversation about a file that takes place in the comments.

You can check out our demo application to see how annotations might fit into your apps.

To learn more, check out our API documentation. Annotations are not yet supported in the Box web or mobile apps. A complete list of supported file types can be found here.

Getting started with annotations
Annotations are available in the embeddable file preview experience through the Get Embed Link of the Box Content API. To enable annotations, developers would need to add a query parameter to the URL they receive as a return of the Get Embed Link call.

First, you would need the File ID of the file you want to display in an app. You would then perform a GET request to the Get Embed Link Endpoint:

curl https://api.box.com/2.0/files/FILE_ID?fields=expiring_embed_link \
-H "Authorization: Bearer ACCESS_TOKEN"

This will return a URL that you can embed:

{
"type": "file",
"id": "34122832467",
"etag": "1",
"expiring_embed_link": {
"url": "https://app.box.com/preview/expiring_embed/[HASH]
}
}

Once you have the URL, you can embed it in an HTML iframe. To enable annotations, you simply need to add a query parameter to the end of the generated embed URL. By default, annotations are turned off. To enable annotations, append the query parameter to the end of the embed URL as “?showAnnotations=true.” This will add a button in the top right-hand corner of the embedded file preview for accessing the annotations functionality.

So your final embed URL will look like:

https://app.box.com/preview/expiring_embed/[HASH]?showAnnotations=true

To get started, sign up for a Box Developer account, or log in to the Box Developer Console to check out our API documentation. If you have any questions about annotations, visit our Developer Forum or reach us on Twitter.