Box Developer Documentation
Log in

Collaboration

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.

string
"12345678"

The unique identifier for this collaboration.

string
"collaboration"

collaboration

Value is always collaboration

object
object
boolean
true

Whether or not the enterprise that owns the content requires a strong password to collaborate on the content.

boolean
true

Whether or not the user has a strong password set for their account. The field is null when a strong password is not required.

object
boolean
true

Whether or not the terms of service have been accepted. The field is null when there is no terms of service required.

Terms of service (Base) object

The terms of service that must be accepted before the collaboration can be accepted. The field is null when there is no terms of service required.

object
boolean
true

Whether or not the enterprise that owns the content requires two-factor authentication to be enabled in order to collaborate on the content.

boolean
true

Whether or not the user has two-factor authentication enabled. The field is null when two-factor authentication is not required.

User (Collaborations) object

The user or group that is granted access.

string / date-time
"2012-12-12T10:55:20-08:00"

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

string / date-time
"2012-12-12T10:53:43-08:00"

When the collaboration object was created.

User (Collaborations) object
[{"id":33224412},{"type":"user"},{"login":"dylan@example.com"},{"name":"Dylan Smith"}]

The user who created the collaboration object.

string / date-time
"2012-12-26T10:53:43-08:00"

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

string
"john@example.com"

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

File / Folder / Web link object

The file or folder to which access is granted. The field is null when the collaboration status is pending.

string / date-time
"2012-12-12T10:53:43-08:00"

When the collaboration object was last modified.

string
"editor"

The level of access granted.

Value is one of editor,viewer,previewer,uploader,previewer uploader,viewer uploader,co-owner,owner

string
"accepted"

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

Value is one of accepted,pending,rejected

Response Example

{
  "id": "12345678",
  "type": "collaboration",
  "acceptance_requirements_status": {
    "strong_password_requirement": {
      "enterprise_has_strong_password_required_for_external_users": true,
      "user_has_strong_password": true
    },
    "terms_of_service_requirement": {
      "is_accepted": true,
      "terms_of_service": {
        "id": "11446498",
        "type": "terms_of_service"
      }
    },
    "two_factor_authentication_requirement": {
      "enterprise_has_two_factor_auth_enabled": true,
      "user_has_two_factor_authentication_enabled": true
    }
  },
  "accessible_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "acknowledged_at": "2012-12-12T10:55:20-08:00",
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": [
    {
      "id": 33224412
    },
    {
      "type": "user"
    },
    {
      "login": "dylan@example.com"
    },
    {
      "name": "Dylan Smith"
    }
  ],
  "expires_at": "2012-12-26T10:53:43-08:00",
  "invite_email": "john@example.com",
  "item": {
    "id": "12345",
    "type": "file",
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "created_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "login": "ceo@example.com",
      "name": "Aaron Levie"
    },
    "description": "Contract for Q1 renewal",
    "etag": "1",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "item_status": "active",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "login": "ceo@example.com",
      "name": "Aaron Levie"
    },
    "name": "Contract.pdf",
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "login": "ceo@example.com",
      "name": "Aaron Levie"
    },
    "parent": {
      "id": "12345",
      "type": "folder",
      "etag": "1",
      "name": "Contracts",
      "sequence_id": "3"
    },
    "path_collection": {
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "name": "Contracts",
          "sequence_id": "3"
        }
      ],
      "total_count": 1
    },
    "purged_at": "2012-12-12T10:53:43-08:00",
    "sequence_id": "3",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "shared_link": {
      "access": "open",
      "download_count": 3,
      "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
      "effective_access": "company",
      "effective_permission": "can_download",
      "is_password_enabled": true,
      "permissions": {
        "can_download": true,
        "can_edit": false,
        "can_preview": true
      },
      "preview_count": 3,
      "unshared_at": "2018-04-13T13:53:23-07:00",
      "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
      "vanity_name": "my_url",
      "vanity_url": "https://acme.app.box.com/v/my_url/"
    },
    "size": 629644,
    "trashed_at": "2012-12-12T10:53:43-08:00"
  },
  "modified_at": "2012-12-12T10:53:43-08:00",
  "role": "editor",
  "status": "accepted"
}