Box Developer Documentation
Log in
Latest version

Update collaboration

put
https://api.box.com/2.0
/collaborations/:collaboration_id

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites.

Request

bearer [ACCESS_TOKEN]
application/json

Path Parameters

stringin pathrequired
1234

The ID of the collaboration

Request Body

booleanin bodyoptional
true

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 owner or co-owners can invite collaborators with a can_view_path of true.

can_view_path can only be used for folder collaborations.

string (date-time)in bodyoptional
"2019-08-29T23:59:00-07:00"

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.

stringin bodyrequired
"editor"

The level of access granted.

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

stringin bodyoptional
"accepted"

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

Value is one of pending,accepted,rejected

Response

application/jsonCollaboration

Returns an updated collaboration object unless the owner has changed.

none

If the role is changed to owner, the collaboration is deleted and a new collaboration is created. The previous owner of the old collaboration will be a co-owner on the new collaboration.

application/jsonClient error

Returns an error if the authenticated user does not have the right permissions to update the collaboration.

Additionally, this error may occur when attempting to update the expires_at field for the collaboration without the Automatically remove invited collaborators: Allow folder owners to extend the expiry date setting enabled in the admin dashboard of the enterprise.

application/jsonClient error

An unexpected client error.

put
Update collaboration
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X PUT "https://api.box.com/2.0/collaborations/1234" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "role": "viewer"
     }'
TypeScript Gen
await client.userCollaborations.updateCollaborationById(collaborationId, {
  role: 'viewer' as UpdateCollaborationByIdRequestBodyRoleField,
} satisfies UpdateCollaborationByIdRequestBody);
Python Gen
client.user_collaborations.update_collaboration_by_id(
    collaboration_id, UpdateCollaborationByIdRole.VIEWER
)
.NET Gen
await client.UserCollaborations.UpdateCollaborationByIdAsync(collaborationId: collaborationId, requestBody: new UpdateCollaborationByIdRequestBody(role: UpdateCollaborationByIdRequestBodyRoleField.Viewer));
Swift Gen (Beta)
try await client.userCollaborations.updateCollaborationById(collaborationId: collaborationId, requestBody: UpdateCollaborationByIdRequestBody(role: UpdateCollaborationByIdRequestBodyRoleField.viewer))
Java
// Accept all pending collaborations
Collection<BoxCollaboration.Info> pendingCollaborations = BoxCollaboration.getPendingCollaborations(api);
for (BoxCollaboration.Info collabInfo : pendingCollaborations) {
    collabInfo.setStatus(BoxCollaboration.Status.ACCEPTED);
    collabInfo.getResource().updateInfo(collabInfo);
}
Python
from boxsdk.object.collaboration import CollaborationRole

collaboration_update = {'role': CollaborationRole.EDITOR, 'can_view_path': False}
collaboration = client.collaboration(collab_id='12345')
updated_collaboration = collaboration.update_info(data=collaboration_update)
.NET
BoxCollaborationRequest requestParams = new BoxCollaborationRequest()
{
    Id = "12345",
    Role = "viewer"
};
BoxCollaboration collab = await client.CollaborationsManager.EditCollaborationAsync(requestParams);
Node
client.collaborations.update('11111', {role: client.collaborationRoles.PREVIEWER})
	.then(collaboration => {
		/* collaboration -> {
			type: 'collaboration',
			id: '11111',
			created_by: 
			{ type: 'user',
				id: '22222',
				name: 'Inviting User',
				login: 'inviter@example.com' },
			created_at: '2015-11-03T18:36:37-08:00',
			modified_at: '2016-11-16T21:01:19-08:00',
			expires_at: null,
			status: 'accepted',
			accessible_by: 
			{ type: 'user',
				id: '33333',
				name: 'Collaborated User',
				login: 'collaborator@example.com' },
			role: 'previewer',
			acknowledged_at: '2015-11-03T18:36:37-08:00',
			item: 
			{ type: 'folder',
				id: '44444',
				sequence_id: '1',
				etag: '1',
				name: 'Collaborated Folder' } }
	 */
	});
iOS
client.collaborations.update(collaborationId: "12345", role: .viewer) { (result: Result<Collaboration, BoxSDKError>) in
    guard case let .success(collaboration) = result else {
        print("Error updating collaboration")
        return
    }

    print("Updated collaboration")
}

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",
    "is_active": true,
    "login": "ceo@example.com",
    "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": "dylan@example.com"
    },
    {
      "name": "Dylan Smith"
    }
  ],
  "expires_at": "2012-12-26T10:53:43-08:00",
  "invite_email": "john@example.com",
  "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": "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": [
        {
          "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"
}