Box Developer Documentation
Log in
Latest version

List folder collaborations

get
https://api.box.com/2.0
/folders/:folder_id/collaborations

Retrieves a list of pending and active collaborations for a folder. This returns all the users that have access to the folder or have been invited to the folder.

Related Guides

Request

bearer [ACCESS_TOKEN]
application/json

Path Parameters

stringin pathrequired
12345

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folder/123 the folder_id is 123.

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.

integer (int64)in queryoptional
1000
1000

The maximum number of items to return per page.

stringin queryoptional
JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii

Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.

This requires usemarker to be set to true.

Response

application/jsonCollaborations

Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned.

This list includes pending collaborations, for which the status is set to pending, indicating invitations that have been sent but not yet accepted.

application/jsonClient error

An unexpected client error.

get
List folder collaborations
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X GET "https://api.box.com/2.0/folders/4353455/collaborations" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
TypeScript Gen
await client.listCollaborations.getFolderCollaborations(folder.id);
Python Gen
client.list_collaborations.get_folder_collaborations(folder.id)
.NET Gen
await client.ListCollaborations.GetFolderCollaborationsAsync(folderId: folder.Id);
Swift Gen (Beta)
try await client.listCollaborations.getFolderCollaborations(folderId: folder.id)
Java
BoxFolder folder = new BoxFolder(api, "id");
Collection<BoxCollaboration.Info> collaborations = folder.getCollaborations();
Python
collaborations = client.folder(folder_id='22222').get_collaborations()
for collab in collaborations:
    target = collab.accessible_by
    print(f'{target.type.capitalize()} {target.name} is collaborated on the folder')
.NET
string folderId = "11111";
BoxCollection<BoxCollaboration> collaborations = await client.FoldersManager
    .GetCollaborationsAsync(folderId);
Node
var folderID = '12345';
client.folders.getCollaborations(folderID)
	.then(collaborations => {
		/* collaborations -> {
			total_count: 1,
			entries: [
				{
					type: 'collaboration',
					id: '11111',
					created_by: {
						type: 'user',
						id: '22222',
						name: 'Example User',
						login: 'user@example.com'
					},
					created_at: '2011-11-29T12:56:35-08:00',
					modified_at: '2012-09-11T15:12:32-07:00',
					expires_at: null,
					status: 'accepted',
					accessible_by: {
						type: 'user',
						id: '33333',
						name: 'Collaborator User',
						login: 'collaborator@example.com'
					},
					role: 'editor',
					acknowledged_at: '2011-11-29T12:59:40-08:00',
					item: null
				}
			]
		}
		*/
	});
iOS
let iterator = client.folders.listCollaborations(folderId: "22222")
iterator.next { results in
    switch results {
    case let .success(page):
        for collaboration in page.entries {
            if let collaborator = collaboration.accessibleBy {
                switch collaborator.collaboratorValue {
                case .user(let user):
                    print("- user: \(user.name ?? "")")
                case .group(let group):
                    print("- group: \(group.name ?? "")")
                }
            }
        }

    case let .failure(error):
        print(error)
    }
}

Response Example

{
  "entries": [
    {
      "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": {
        "application_type": "hubs",
        "id": "12345678",
        "type": "app_item"
      },
      "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",
      "id": "12345678",
      "invite_email": "john@example.com",
      "is_access_only": true,
      "item": {
        "etag": "1",
        "id": "12345",
        "type": "file",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "name": "Contract.pdf",
        "sequence_id": "3",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "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",
        "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"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "parent": {
          "etag": "1",
          "id": "12345",
          "type": "folder",
          "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",
        "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",
      "type": "collaboration"
    }
  ],
  "limit": 1000,
  "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
  "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih"
}