Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Create collaboration

post
https://api.box.com/2.0
/collaborations

Adds a collaboration for a single user or a single group to a file or folder.

Collaborations can be created using email address, user IDs, or a group IDs.

If a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited.

If collaboration is in pending status, the following fields are redacted:

  • login and name are hidden if a collaboration was created using user_id,
  • name is hidden if a collaboration was created using login.

Request

bearer [ACCESS_TOKEN]
application/json

Query Parameters

string arrayin queryoptional
id,type,name

A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response.

Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.

booleanin queryoptional
true

Determines if users should receive email notification for the action performed.

Request Body

objectin body

The user or group to give access to the item.

stringin bodyrequired
"23522323"

The ID of the user or group.

Alternatively, use login to specify a user by email address.

stringin bodyrequired
"user"

The type of collaborator to invite.

Value is one of user,group

stringin bodyrequired
"john@example.com"

The email address of the user to grant access to the item.

Alternatively, use id to specify a user by user ID.

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"

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

booleanin bodyoptional
true

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 the path to the root folder for the shared item.

objectin body

The item to attach the comment to.

stringin bodyrequired
"11446498"

The ID of the item that will be granted access to

stringin bodyrequired
"file"

The type of the item that this collaboration will be granted access to

Value is one of file,folder

stringin bodyrequired
"editor"

The level of access granted.

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

Response

application/jsonCollaboration

Returns a new collaboration object.

application/jsonClient error

Returns an error when the user does not have the right permissions to create the collaboration.

  • forbidden_by_policy: Creating a collaboration is forbidden due to information barrier restrictions.
application/jsonClient error

An unexpected client error.

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

Request Example

cURL
curl -i -X POST "https://api.box.com/2.0/collaborations" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "item": {
         "type": "file",
         "id": "11446498"
       },
       "accessible_by": {
         "type": "user",
         "login": "user@example.com"
       },
       "role": "editor"
     }'
TypeScript Gen
await client.userCollaborations.createCollaboration({
  item: {
    type: 'file' as CreateCollaborationRequestBodyItemTypeField,
    id: file.id,
  } satisfies CreateCollaborationRequestBodyItemField,
  accessibleBy: {
    type: 'user' as CreateCollaborationRequestBodyAccessibleByTypeField,
    id: getEnvVar('USER_ID'),
  } satisfies CreateCollaborationRequestBodyAccessibleByField,
  role: 'editor' as CreateCollaborationRequestBodyRoleField,
} satisfies CreateCollaborationRequestBody);
Python Gen
client.user_collaborations.create_collaboration(
    CreateCollaborationItem(
        type=CreateCollaborationItemTypeField.FILE.value, id=file.id
    ),
    CreateCollaborationAccessibleBy(
        type=CreateCollaborationAccessibleByTypeField.USER.value,
        id=get_env_var("USER_ID"),
    ),
    CreateCollaborationRole.EDITOR.value,
)
.NET Gen
await client.UserCollaborations.CreateCollaborationAsync(requestBody: new CreateCollaborationRequestBody(item: new CreateCollaborationRequestBodyItemField() { Type = CreateCollaborationRequestBodyItemTypeField.File, Id = file.Id }, accessibleBy: new CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.User) { Id = Utils.GetEnvVar(name: "USER_ID") }, role: CreateCollaborationRequestBodyRoleField.Editor));
Swift Gen (Beta)
try await client.userCollaborations.createCollaboration(requestBody: CreateCollaborationRequestBody(item: CreateCollaborationRequestBodyItemField(type: CreateCollaborationRequestBodyItemTypeField.file, id: file.id), accessibleBy: CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.user, id: Utils.getEnvironmentVariable(name: "USER_ID")), role: CreateCollaborationRequestBodyRoleField.editor))
Java
BoxCollaborator user = new BoxUser(api, "user-id")
BoxFolder folder = new BoxFolder(api, "folder-id");
folder.collaborate(user, BoxCollaboration.Role.EDITOR);
Python
from boxsdk.object.collaboration import CollaborationRole

user = client.user(user_id='11111')
collaboration = client.folder(folder_id='22222').collaborate(user, CollaborationRole.VIEWER)

collaborator = collaboration.accessible_by
item = collaboration.item
has_accepted = 'has' if collaboration.status == 'accepted' else 'has not'
print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"')
.NET
// collaborate folder 11111 with user 22222
BoxCollaborationRequest requestParams = new BoxCollaborationRequest()
{
    Item = new BoxRequestEntity()
    {
        Type = BoxType.folder,
        Id = "11111"
    },
    Role = "editor",
    AccessibleBy = new BoxCollaborationUserRequest()
    {
        Type = BoxType.user,
        Id = "22222"
    }
};
BoxCollaboration collab = await client.CollaborationsManager.AddCollaborationAsync(requestParams);
Node
// Invite user 123456 to collaborate on folder 987654
client.collaborations.createWithUserID('123456', '987654', client.collaborationRoles.EDITOR)
	.then(collaboration => {
		/* collaboration -> {
			type: 'collaboration',
			id: '11111',
			created_by: 
			{ type: 'user',
				id: '22222',
				name: 'Inviting User',
				login: 'inviter@example.com' },
			created_at: '2016-11-16T21:33:31-08:00',
			modified_at: '2016-11-16T21:33:31-08:00',
			expires_at: null,
			status: 'accepted',
			accessible_by: 
			{ type: 'user',
				id: '123456',
				name: 'Collaborator User',
				login: 'collaborator@example.com' },
			role: 'editor',
			acknowledged_at: '2016-11-16T21:33:31-08:00',
			item: 
			{ type: 'folder',
				id: '987654',
				sequence_id: '0',
				etag: '0',
				name: 'Collaborated Folder' } }
		*/
	});
iOS
client.collaborations.create(
    itemType: "folder",
    itemId: "22222",
    role: .editor,
    accessibleBy: "33333",
    accessibleByType: .user
) { (result: Result<Collaboration, BoxSDKError>) in
    guard case let .success(collaboration) = result else {
        print("Error creating collaboration")
        return
    }

    print("Collaboration successfully created")
}

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": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ],
      "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"
}