Skip to main content
POST
/
collaborations
cURL
curl -i -X POST "https://api.box.com/2.0/collaborations" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "item": {
         "type": "file",
         "id": "11446498"
       },
       "accessible_by": {
         "type": "user",
         "login": "[email protected]"
       },
       "role": "editor"
     }'
{
  "id": "12345678",
  "type": "collaboration",
  "item": {
    "id": "12345",
    "type": "file",
    "etag": "1",
    "sequence_id": "3",
    "name": "Contract.pdf",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "description": "Contract for Q1 renewal",
    "size": 629644,
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "id": "12345",
          "type": "folder",
          "etag": "1",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ]
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "trashed_at": "2012-12-12T10:53:43-08:00",
    "purged_at": "2012-12-12T10:53:43-08:00",
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "[email protected]"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "[email protected]"
    },
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "[email protected]"
    },
    "shared_link": {
      "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
      "effective_access": "company",
      "effective_permission": "can_download",
      "is_password_enabled": true,
      "download_count": 3,
      "preview_count": 3,
      "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
      "vanity_url": "https://acme.app.box.com/v/my_url/",
      "vanity_name": "my_url",
      "access": "open",
      "unshared_at": "2018-04-13T13:53:23-07:00",
      "permissions": {
        "can_download": true,
        "can_preview": true,
        "can_edit": false
      }
    },
    "parent": {
      "id": "12345",
      "type": "folder",
      "etag": "1",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "item_status": "active"
  },
  "app_item": {
    "id": "12345678",
    "type": "app_item",
    "application_type": "hubs"
  },
  "accessible_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]",
    "is_active": true
  },
  "invite_email": "[email protected]",
  "role": "editor",
  "expires_at": "2012-12-26T10:53:43-08:00",
  "is_access_only": true,
  "status": "accepted",
  "acknowledged_at": "2012-12-12T10:55:20-08:00",
  "created_by": [
    {
      "id": 33224412
    },
    {
      "type": "user"
    },
    {
      "login": "[email protected]"
    },
    {
      "name": "Dylan Smith"
    }
  ],
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "acceptance_requirements_status": {
    "terms_of_service_requirement": {
      "is_accepted": true,
      "terms_of_service": {
        "id": "11446498",
        "type": "terms_of_service"
      }
    },
    "strong_password_requirement": {
      "enterprise_has_strong_password_required_for_external_users": true,
      "user_has_strong_password": true
    },
    "two_factor_authentication_requirement": {
      "enterprise_has_two_factor_auth_enabled": true,
      "user_has_two_factor_authentication_enabled": true
    }
  }
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
fields
string[]

A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response.

Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.

​
notify
boolean

Determines if users should receive email notification for the action performed.

Body

application/json
​
item
object
required

The item to attach the comment to.

​
accessible_by
object
required

The user or group to give access to the item.

​
role
enum<string>
required

The level of access granted.

Available options:
editor,
viewer,
previewer,
uploader,
previewer uploader,
viewer uploader,
co-owner
Example:

"editor"

​
is_access_only
boolean

If set to true, collaborators have access to shared items, but such items won't be visible in the All Files list. Additionally, collaborators won't see the path to the root folder for the shared item.

Example:

true

​
can_view_path
boolean

Determines if the invited users can see the entire parent path to the associated folder. The user will not gain privileges in any parent folder and therefore can not see content the user is not collaborated on.

Be aware that this meaningfully increases the time required to load the invitee's All Files page. We recommend you limit the number of collaborations with can_view_path enabled to 1,000 per user.

Only an owner or co-owners can invite collaborators with a can_view_path of true. Only an owner can update can_view_path on existing collaborations.

can_view_path can only be used for folder collaborations.

When you delete a folder with can_view_path=true, collaborators may still see the parent path. For instructions on how to remove this, see Even though a folder invited via can_view_path is deleted, the path remains displayed.

Example:

true

​
expires_at
string<date-time>

Set the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item.

This feature will only work if the Automatically remove invited collaborators: Allow folder owners to extend the expiry date setting has been enabled in the Enterprise Settings of the Admin Console. When the setting is not enabled, collaborations can not have an expiry date and a value for this field will be result in an error.

Example:

"2019-08-29T23:59:00-07:00"

Response

Returns a new collaboration object.

Collaborations define access permissions for users and groups to files and folders, similar to access control lists. A collaboration object grants a user or group access to a file or folder with permissions defined by a specific role.

​
id
string
required

The unique identifier for this collaboration.

Example:

"12345678"

​
type
enum<string>
required

The value will always be collaboration.

Available options:
collaboration
Example:

"collaboration"

​
item
File · object

The file or folder to which access is granted. The field is null when the collaboration status is pending or the collaboration is created on an app item (see app_item field).

​
app_item
App item · object

An app_item to which access is granted. The field is null when the collaboration is created on an item (see item field), or the app_item is inaccessible. The role cascades to all items associated with the app_item.

​
accessible_by
User (Collaborations) · object

A mini representation of a user, can be returned only when the status is pending.

​
invite_email
string | null

The email address used to invite an unregistered collaborator, if they are not a registered user.

Example:

"[email protected]"

​
role
enum<string>

The level of access granted.

Available options:
editor,
viewer,
previewer,
uploader,
previewer uploader,
viewer uploader,
co-owner,
owner
Example:

"editor"

​
expires_at
string<date-time> | null

When the collaboration will expire, or null if no expiration date is set.

Example:

"2012-12-26T10:53:43-08:00"

​
is_access_only
boolean

If set to true, collaborators have access to shared items, but such items won't be visible in the All Files list. Additionally, collaborators won't see the path to the root folder for the shared item.

Example:

true

​
status
enum<string>

The status of the collaboration invitation. If the status is pending, login and name return an empty string.

Available options:
accepted,
pending,
rejected
Example:

"accepted"

​
acknowledged_at
string<date-time>

When the status of the collaboration object changed to accepted or rejected.

Example:

"2012-12-12T10:55:20-08:00"

​
created_by
User (Collaborations) · object

The user who created the collaboration object.

Example:
[
  { "id": 33224412 },
  { "type": "user" },
  { "login": "[email protected]" },
  { "name": "Dylan Smith" }
]
​
created_at
string<date-time>

When the collaboration object was created.

Example:

"2012-12-12T10:53:43-08:00"

​
modified_at
string<date-time>

When the collaboration object was last modified.

Example:

"2012-12-12T10:53:43-08:00"

​
acceptance_requirements_status
object