Box Developer Documentation
Log in

Share Content with User

Guides Collaborations Share Content with User
Edit this page

Share Content with User

To share content with a user, create a collaboration using the user ID or email address, the ID of the content, and the role or permissions level the user should have when accessing the content. The collaboration roles are editor,viewer, previewer, uploader, previewer uploader, viewer uploader,co-owner, or owner. For a full description of each role, please refer to our support documentation.

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")
}

Nested objects

When creating a collaboration there are two nested objects within the request body: accessible_by and item.

The accessible_by object specifies who the item should be shared with and includes a group id and the type. The type field should always be set to user.

The item object specifies what is being shared. It includes a type field which should be set as file and an id for that file.