Search⌘ K
Home/
Courses/
Get Started with the Dropbox API in Python

Add, List, and Remove a File Member

Learn how to add a new file member, get a list of all members with access to a file, and remove a specific file member using the Dropbox API.

We'll cover the following...

In this lesson, we’ll learn about the sharing namespace offered by the Dropbox API. The endpoints of this namespace are used to create and manage shared links and folders. We’ll explore the following operations in this lesson:

  • add_file_member
  • list_file_members
  • remove_file_member_2

Note: The endpoints of the sharing namespace only support applications with full Dropbox access. For example, if you’ve created an application that has “App folder” access, then this endpoint won’t work.

Add a member to a file

The /sharing/add_file_member endpoint adds a user to a file. This endpoint requires us to enable the sharing.write permission to perform this task.

Request parameters

Let’s see which parameters we can pass to this endpoint call.

Parameter Name

Description

Format

Required

file

This defines the file to which we want to add a member. We can use the name of the file with the complete path or ID of a file.

String

Yes

members

This is a list of users that we want to add to the file we indicated in the previous parameter. Members can be specified by their Dropbox ID or email address.

String

Yes

custom_message

We can include a message to be sent to the newly added member.

String

No

quiet

This parameter tells us how the member should be notified—for example, by email or device notifications. By default, it’s set to False.

Boolean

No

access_level

This defines the role of our newly added member. It could be owner, editor, viewer, or viewer_no_comment. A member with viewer_no_comment rights can only view the shared file and doesn’t have access to the file’s comments. The default value is viewer.

Object

No

add_message_as_comment

If this parameter is set to True, then the custom message will be added to the file as a comment. The default value for this parameter is False.

Boolean

No

In the code below, we’ll add a member to a file.

Python 3.8
import requests
import json
url = "https://api.dropboxapi.com/2/sharing/add_file_member"
headers = {
    "Authorization": "Bearer {{TOKEN}}",
    "Content-Type": "application/json"
}
#Please replace email placeholder with correct email ID.
data = {
    "file": "/home/TestFolder/demo.png",
    "members": [{".tag":"email","email":"user_id@gmail.com"}],
    "custom_message": "You have been added as a viewer to this file by the admin...",
    "quiet": False,
    "access_level": {".tag":"viewer"},
    "add_message_as_comment": False
}
r = requests.request("POST",url, headers=headers, data=json.dumps(data))
print(json.dumps(r.json(), indent=4))

In the code above, we see the following:

  • Lines 11–18: We define our data object.
  • Line 12: This shows our file’s path with the file name at the end of the string.
  • Line 13: This shows the list of members to add, which includes their tag and email address. The tag defines whether a member will be added with their Dropbox ID or their email ID.
  • Lines 14–17: We present the remaining parameters as we’ve defined them in the table above.
  • Line 20: We define the POST request.
  • Line 21: We print the response.

Note: We can only specify the access_levels parameter as editor or viewer.

Response

The code will return a list that includes metadata of the added member (such as their role) and the outcome or status of this call.

List file members

This endpoint will give us a list of all the members that have access to the shared file. The /sharing/list_file_members endpoint requires us to enable the sharing.read permission to perform this task.

Request parameters

Let’s see some of the parameters in the table below that we’ll need to use in our practice code.

Parameter Name

Description

Format

Required

file

This is the ID of the file for which we want to get a list of members.

String

Yes

include_inherited

This tells us if we want to include members who have obtained access to a file from a shared parent folder. By default its value is set to True.

Boolean

No

limit

This is the maximum number of members to return per query. By default its value is 100.

UInt32

No

In the code below, we’ll use the search_v2 endpoint to get the file ID for demo.png.

Python 3.8
import requests
import json
url = "https://api.dropboxapi.com/2/files/search_v2"
headers = {
    "Authorization": "Bearer {{TOKEN}}",
    "Content-Type": "application/json"
}
data = {
    "query": "demo",
    "options": {
        "path":"/home/TestFolder"
        }
}
r = requests.request("POST",url, headers=headers, data=json.dumps(data))
print(json.dumps(r.json(), indent=4))

The code above will give all files with the name demo. Copy the ID of demo.png and paste it into line 12 of the code below.

Python 3.8
import requests
import json
url = "https://api.dropboxapi.com/2/sharing/list_file_members"
headers = {
    "Authorization": "Bearer {{TOKEN}}",
    "Content-Type": "application/json"
}
data = {
    "file": "Paste the ID here",
    "include_inherited": True
}
r = requests.request("POST",url, headers=headers, data=json.dumps(data))
print(json.dumps(r.json(), indent=4))

In the code above, we see the following:

  • Lines 11–14: We define the data object, which includes the file and include_inherited parameters. The file ID is for the demo.png file, which is under TestFolder.
  • Line 16: This is the HTTP request.
  • Line 17: This is the print statement.

Response

Successful execution of the list_file_members endpoint returns three separate lists of users, groups, and invitees. It also returns a cursor. Let’s describe these response fields in some more detail.

  • The field users indicates a list of members who have access to the shared file.
    • The access_type defines the role of the member—for example, if the member is the owner, viewer, editor, or viewer_no_comment.
    • A user defines the account information of the file member (user)—for example, their name, id, email, and so on.
    • The value is_inherited tells us if the file member was given or obtained access from the parent folder. If this is the case, then its value is True.
  • The field invitees is a list composed of members who were invited to this file but haven’t registered and/or accessed this invitation. It includes almost all the same fields included in the users list.
  • The cursor is used to fetch other members if there are other members who have not been returned in our results.

Remove a file member

Let’s remove a specific member from a file using the /sharing/remove_file_member_2 endpoint of the sharing namespace.

Request parameters

This request takes two required parameters. The first is the file parameter, which is assigned the file ID, and the second is the member parameter, which states the tag and email of the member to be removed.

Now, let’s remove the member that we added to the demo.png file using the add_file_member endpoint.

Parameter Name

Description

Format

Required

file

This is the file ID or path, including the file's name, from which we want to remove a member.

String

Yes

member

We can indicate here how we want to remove a file member. It’s specified by the value of tag. If it’s dropbox_id, then we have to provide the user's Dropbox ID, and if it’s email, then we can remove a member by using their email address.

Open Union

Yes

In the code below, we’ll remove a specific member from a file.

Python 3.8
import requests
import json
url = "https://api.dropboxapi.com/2/sharing/remove_file_member_2"
headers = {
    "Authorization": "Bearer {{TOKEN}}",
    "Content-Type": "application/json"
}
data = {
        "file": "/home/TestFolder/demo.png",
        "member": {".tag":"email","email":"user_id@gmail.com"}
}
r = requests.request("POST",url, headers=headers, data=json.dumps(data))
print(json.dumps(r.json(), indent=4))

In the code above, we see the following:

  • Line 12: This shows the file parameter, we’ve specified the path of our demo.png file.
  • Line 13: This shows the member and includes the tag that defines if we’ll specify the file member’s Dropbox ID or email address. Next, we have given an email ID based on the tag type.
  • Line 16: This is the POST request to the endpoint.
  • Line 17: We print the response of our call.

Response

The code only returns the tag field with the success value.