> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Collaborations resources
Collaborations define access permissions for users and groups to files and folders, similar to access control lists.
## 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.
| Property | Type | Required | Description |
| -------------------------------- | ----------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Yes | The unique identifier for this collaboration. |
| `type` | `enum` | 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](/reference/app-item-associations-resources#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` | 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` | 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)](/reference/users-resources#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 | |
```json Example theme={null}
{
"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.
| 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](#collaboration) | No | A list of collaborations. |
```json Example theme={null}
{
"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.
| 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](#collaboration) | No | A list of collaborations. |
```json Example theme={null}
{
"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
}
}
}
]
}
```