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.Attributes and example
Attributes and example
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The unique identifier for this collaboration. |
type | enum<string> | Yes | The value will always be collaboration. Available options: collaboration. |
item | Collaboration item | No | 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). Can be null. |
app_item | App item | No | 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. Can be null. |
accessible_by | Collaboration access grantee | No | |
invite_email | string | No | The email address used to invite an unregistered collaborator, if they are not a registered user. Can be null. |
role | enum<string> | No | The level of access granted. Available options: editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner, owner. |
expires_at | string | No | When the collaboration will expire, or null if no expiration date is set. Can be null. |
is_access_only | boolean | No | 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. |
status | enum<string> | No | The status of the collaboration invitation. If the status is pending, name returns an empty string. Available options: accepted, pending, rejected. |
acknowledged_at | string | No | When the status of the collaboration object changed to accepted or rejected. |
created_by | User (Collaborations) | No | The user who created the collaboration object. |
created_at | string | No | When the collaboration object was created. |
modified_at | string | No | When the collaboration object was last modified. |
acceptance_requirements_status | object | No |
Example
{
"id": "12345678",
"type": "collaboration",
"item": {
"id": "12345",
"etag": "1",
"type": "file",
"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",
"etag": "1",
"type": "folder",
"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": "ceo@example.com"
},
"modified_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"owned_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"shared_link": {
"url": "https://www.box.com/s/vspke7y05sb214wjokpk",
"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",
"effective_access": "company",
"effective_permission": "can_download",
"unshared_at": "2018-04-13T13:53:23-07:00",
"is_password_enabled": true,
"permissions": {
"can_download": true,
"can_preview": true,
"can_edit": false
},
"download_count": 3,
"preview_count": 3
},
"parent": {
"id": "12345",
"etag": "1",
"type": "folder",
"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": "ceo@example.com",
"is_active": true
},
"invite_email": "john@example.com",
"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": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com",
"is_active": true
},
"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
}
}
}
Collaborations
A list of collaborations.Attributes and example
Attributes and example
| Property | Type | Required | Description |
|---|---|---|---|
limit | integer | No | The limit that was used for these entries. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
next_marker | string | No | The marker for the start of the next page of results. Can be null. |
prev_marker | string | No | The marker for the start of the previous page of results. Can be null. |
entries | array of Collaboration | No | A list of collaborations. |
Example
{
"limit": 1000,
"next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
"prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
"entries": [
{
"id": "12345678",
"type": "collaboration",
"item": {
"id": "12345",
"etag": "1",
"type": "file",
"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",
"etag": "1",
"type": "folder",
"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": "ceo@example.com"
},
"modified_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"owned_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"shared_link": {
"url": "https://www.box.com/s/vspke7y05sb214wjokpk",
"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",
"effective_access": "company",
"effective_permission": "can_download",
"unshared_at": "2018-04-13T13:53:23-07:00",
"is_password_enabled": true,
"permissions": {
"can_download": true,
"can_preview": true,
"can_edit": false
},
"download_count": 3,
"preview_count": 3
},
"parent": {
"id": "12345",
"etag": "1",
"type": "folder",
"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": "ceo@example.com",
"is_active": true
},
"invite_email": "john@example.com",
"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": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com",
"is_active": true
},
"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
}
}
}
]
}
Collaborations
A list of collaborations.Attributes and example
Attributes and example
| Property | Type | Required | Description |
|---|---|---|---|
total_count | integer | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than total_count. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
limit | integer | No | The limit that was used for these entries. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
offset | integer | No | The 0-based offset of the first entry in this set. This will be the same as the offset query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
entries | array of Collaboration | No | A list of collaborations. |
Example
{
"total_count": 5000,
"limit": 1000,
"offset": 2000,
"entries": [
{
"id": "12345678",
"type": "collaboration",
"item": {
"id": "12345",
"etag": "1",
"type": "file",
"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",
"etag": "1",
"type": "folder",
"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": "ceo@example.com"
},
"modified_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"owned_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"shared_link": {
"url": "https://www.box.com/s/vspke7y05sb214wjokpk",
"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",
"effective_access": "company",
"effective_permission": "can_download",
"unshared_at": "2018-04-13T13:53:23-07:00",
"is_password_enabled": true,
"permissions": {
"can_download": true,
"can_preview": true,
"can_edit": false
},
"download_count": 3,
"preview_count": 3
},
"parent": {
"id": "12345",
"etag": "1",
"type": "folder",
"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": "ceo@example.com",
"is_active": true
},
"invite_email": "john@example.com",
"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": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com",
"is_active": true
},
"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
}
}
}
]
}