Skip to main content
API version 2024.0 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
example: 12345678The unique identifier for this collaboration.
​
type
string
example: collaborationThe value will always be collaboration.Value is always collaboration
​
acceptance_requirements_status
object
​
accessible_by
Group (Mini)/User (Collaborations)object
The user or group that is granted access.
​
acknowledged_at
string(date-time)
example: 2012-12-12T10:55:20-08:00When the status of the collaboration object changed to accepted or rejected.
​
app_item
App itemobject
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.
​
created_at
string(date-time)
example: 2012-12-12T10:53:43-08:00When the collaboration object was created.
​
created_by
User (Collaborations)object
example: [{"id":33224412},{"type":"user"},{"login":"[email protected]"},{"name":"Dylan Smith"}]The user who created the collaboration object.
​
expires_at
string(date-time)
example: 2012-12-26T10:53:43-08:00When the collaboration will expire, or null if no expiration date is set.
​
invite_email
string
example: [email protected]The email address used to invite an unregistered collaborator, if they are not a registered user.
​
is_access_only
boolean
example: trueIf 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.
​
item
File/Folder/Web linkobject
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).
​
modified_at
string(date-time)
example: 2012-12-12T10:53:43-08:00When the collaboration object was last modified.
​
role
string
example: editorThe level of access granted.Value is one of editor,viewer,previewer,uploader,previewer uploader,viewer uploader,co-owner,owner
​
status
string
example: acceptedThe status of the collaboration invitation. If the status is pending, login and name return an empty string.Value is one of accepted,pending,rejected
{
  "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",
    "is_active": true,
    "login": "[email protected]",
    "name": "Aaron Levie"
  },
  "acknowledged_at": "2012-12-12T10:55:20-08:00",
  "app_item": {
    "id": "12345678",
    "type": "app_item",
    "application_type": "hubs"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": [
    {
      "id": 33224412
    },
    {
      "type": "user"
    },
    {
      "login": "[email protected]"
    },
    {
      "name": "Dylan Smith"
    }
  ],
  "expires_at": "2012-12-26T10:53:43-08:00",
  "invite_email": "[email protected]",
  "is_access_only": true,
  "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": "[email protected]",
      "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": "[email protected]",
      "name": "Aaron Levie"
    },
    "name": "Contract.pdf",
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "login": "[email protected]",
      "name": "Aaron Levie"
    },
    "parent": {
      "id": "12345",
      "type": "folder",
      "etag": "1",
      "name": "Contracts",
      "sequence_id": "3"
    },
    "path_collection": {
      "entries": [
        {
          "etag": "1",
          "id": "12345",
          "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"
}