BObox
Collaborations

Update collaboration

Changed on

Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites. In case of accepting collaboration invite, role is not required.

put/collaborations/{collaboration_id}

Request

  • Base URL
    https://api.box.com/2.0
  • URL
    https://api.box.com/2.0/collaborations/{collaboration_id}
  • Auth
    OAuth 2
    Authorization code: https://account.box.com/api/oauth2/authorize
    Token URL: https://api.box.com/oauth2/token

Path parameters

collaboration_idstring required

The ID of the collaboration.

Request body

role'editor' | 'viewer' | 'previewer' | 'uploader' | 'previewer uploader' | 'viewer uploader' | 'co-owner' | 'owner'

The level of access granted.

status'pending' | 'accepted' | 'rejected'

Set the status of a pending collaboration invitation, effectively accepting, or rejecting the invite.

expires_atstring date-time

Update 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.

Additionally, a collaboration can only be given an expiration if it was created after the Automatically remove invited collaborator setting was enabled.

can_view_pathboolean

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 request

{
  "role": "editor",
  "status": "accepted",
  "expires_at": "2019-08-29T23:59:00-07:00",
  "can_view_path": true
}

Response

Returns an updated collaboration object unless the owner has changed.

idstring required

The unique identifier for this collaboration.

type'collaboration' required

The value will always be collaboration.

invite_emailstring nullable

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

role'editor' | 'viewer' | 'previewer' | 'uploader' | 'previewer uploader' | 'viewer uploader' | 'co-owner' | 'owner'

The level of access granted.

expires_atstring date-time nullable

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

is_access_onlyboolean

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'accepted' | 'pending' | 'rejected'

The status of the collaboration invitation. If the status is pending, name returns an empty string.

acknowledged_atstring date-time

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

created_atstring date-time

When the collaboration object was created.

modified_atstring date-time

When the collaboration object was last modified.

Example response

{
  "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"
    }
  },
  "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
    }
  }
}

Changes

  • c4d5303fa5c3Revision changes
    • breaking

      added to the / response property oneOf list for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • info

      removed from the / response property oneOf list for the response status