Introducing the Box File Collaboration API

Starting today, the collaborations object in the Box Content API will now support file-level collaborations in addition to folder-level collaborations. Collaborations are used to set and apply permissions for users and groups to files and folders, similar to access control lists. This means that now users or groups can be invited to access and collaborate on individual file objects, as opposed to having to invite users or groups into folders in order to provide access to a particular file.

The file collaboration API allows you more granularly manage access to content in your apps; controlling exactly which users can access what files. For example, if you're building a patient vault as part of a patient portal or mobile application, you could allow a patient to invite another healthcare provider to get a second opinion on a single analysis or medical image, instead of providing access to all the documents in their account. This helps preserve security and privacy in your app while making it easy for users to share and collaborate on content.

The file collaborations API was built to support a recent update to the web experience for Box Notes. In Box Notes, Box's collaborative notetaking tool, we wanted to provide the ability to share an individual Box Note with anyone you're working with, such as sharing meeting minutes with other attendees. Previously, a Box user needed to have access to the containing folder in order to access and edit an individual Box Note. This created friction for on-the-fly sharing and collaborating. Now, with file collaborations, users can add others as collaborators to an individual Box Note, without inviting them to the Box Note's containing folder.

Here's how it works:

1. Grab the File and User IDs - in order to create a file collaboration (or, set permissions for a user or group on a file), you'll need to provide the file ID and the ID for the user or group you wish to manage access for.

2. Determine collaboration role - When inviting a user or group of users as a collaborator on a file, you will have the ability to control the level of access that user (or users) has to that file. Box offers seven different levels of permissions that you can choose from to control exactly what a user can do with the file. You can learn more about our access levels in our support documentation.

3. Create a collaboration - the POST request to create a collaboration is quite simple. In the request, you will specify the item (the file or folder), the user or group you wish to grant access to, and the collaboration role you wish to grant them.

curl https://api.box.com/2.0/collaborations \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"item": { "id": "11446500", "type": "file"}, "accessible_by": { "id": "17738362", "type": "user" }, "role": "viewer"}' \
-X POST

Upon request, a new collaboration is returned. You might receive errors if the IDs are invalid or if the user attempting to add a collaborator does not have sufficient access permissions to create a collaboration.

{
    "type": "collaboration",
    "id": "791293",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "Mike Schwartz",
        "login": "[email protected]"
    },
    "created_at": "2016-12-12T10:54:37-08:00",
    "modified_at": "2016-12-12T11:30:43-08:00",
    "expires_at": null,
    "status": "accepted",
    "accessible_by": {
        "type": "user",
        "id": "18203124",
        "name": "Mike",
        "login": "[email protected]"
    },
    "role": "viewer",
    "acknowledged_at": "2016-12-12T11:30:43-08:00",
    "item": {
        "type": "file",
        "id": "11446500",
        "sequence_id": "0",
        "etag": "0",
        "name": "My Presentation"
    }
}

You can also retrieve any collaboration objects for a particular file using the following call (11446500 in the URL below represents the file_id):

curl https://api.box.com/2.0/files/11446500/collaborations \
-H "Authorization: Bearer ACCESS_TOKEN"

This will return a collection of collaboration objects. If there are no collaborations on the file, an empty collection will be returned.

{
    "total_count": 1,
    "entries": [
        {
            "type": "collaboration",
            "id": "791293",
            "created_by": {
                "type": "user",
                "id": "17738362",
                "name": "Mike Schwartz",
                "login": "[email protected]"
            },
"created_at": "2016-12-12T10:54:37-08:00",
    "modified_at": "2016-12-12T11:30:43-08:00",
    "expires_at": null,
    "status": "accepted",
    "accessible_by": {
        "type": "user",
        "id": "18203124",
        "name": "Mike",
        "login": "[email protected]"
    },
            "role": "viewer",
"acknowledged_at": "2016-12-12T11:30:43-08:00",
            "item": null
        }
    ]
}

To learn more about file collaborations, you can check out our API documentation for collaborations. If you have any questions, please feel free to post them in our Developer Forum or reach out to us on Twitter.