Share and Add a Member to a Folder

Learn how to share a folder and add one or more members to it with the Dropbox API.

We'll cover the following

In this lesson, we’ll explore two new endpoints of the sharing namespace, which include the following:

  • share_folder
  • add_folder_member

Share a folder

The /sharing/share_folder is used to create a shared link to a folder. This endpoint requires us to enable the sharing.write permission to do this task. Most of the time, sharing a folder is a synchronous process, but sometimes it can be asynchronous.

Request parameters

Let’s see some of this endpoint’s parameters in the following table. We’ll use only the required parameters in our example code.

Parameter Name

Description

Format/Value

Required

path

This is the path of the folder that we want to share. The endpoint will create a new folder if it’s not found in the specified directory.

String

Yes

acl_update_policy

This field specifies which members can make changes to a folder’s access control list. It tells who can add and remove members to this folder.

The value can either be owner or editor.

No

force_async

This field defines that the shared operation must be asynchronous. The default value is False.

Boolean

No

actions

By using this field, we can define a list of actions that an authenticated user can do with the folder. Some of the action values are mentioned in the next field.

change_options, display_viewer_info,

edit_contents,

enable_viewer_info, invite_viewer_no_comment


No

link_settings

This parameter states the settings of the shared link.

It can specify access_level, password, expiry, and audience.

No

Let’s see the functionality of the share_folder endpoint in the code below.

Press + to interact
import requests
import json
url = "https://api.dropboxapi.com/2/sharing/share_folder"
headers = {
    "Authorization": "Bearer {{TOKEN}}",
    "Content-Type": "application/json"
}
data = {
    "path": "/home/SharedFolder"
}
r = requests.request("POST",url, headers=headers, data=json.dumps(data))
print(json.dumps(r.json(), indent=4))

When we execute the code above, the ID of the shared folder and preview URL will automatically be extracted from the response. Please click the “Save” button; we’ll use this ID in the next section.

In the code above, we see the following:

  • Line 12: This shows the path to the folder that we want to share. At this point, we don’t have the folder SharedFolder in the /home directory of our Dropbox, but we have defined it in the path parameter.

  • Line 15: We create a POST request to the specified Url.

  • Line 16: We print the response.

Response

We’ll notice that a SharedFolder has been created in the /home directory, and it has a symbol that indicates it’s been shared on its folder icon (shown in the image below). If the response contains async_job_id, then it means that the operation is asynchronous. This ID will be used to check the status of the operation.

In the table below, we’ve shown some of the response fields of the share_folder endpoint.

Fields

Description

Format/Value

access_type

This shows what type of access a current user has for this shared folder.

Its values can be owner, editor, viewer, or viewer_no_comment.

name

This is the name of the folder.

String

policy

This provides all of the policy types related to this shared folder.

acl_update_policy, shared_link_policy, viewer_info_ policy, member_policy, and resolved_member_policy

preview_url

This is an important field. Its value is used to access the shared folder in a web preview.

String

shared_folder_id

This is the ID of the shared folder, which will be used in the next section.

String

Note: The preview_url for the endpoint above can be shared with anyone, but they must first request access from the owner.

If the async_job_id status is returned by the code above, then we’ll use the check_job_status endpoint in the following code. We’ll replace the placeholder {async_job_id} in line 12 with the async_job_id value returned by the previous block of code. It’ll produce a complete response once the operation is done.

Press + to interact
import requests
import json
url = "https://api.dropboxapi.com/2/sharing/check_job_status"
headers = {
    "Authorization": "{{TOKEN}}",
    "Content-Type": "application/json"
}
data = {
    "async_job_id": "{async_job_id}"
}
r = requests.request("POST",url, headers=headers, data=json.dumps(data))
print(json.dumps(r.json(), indent=4))

Add a folder member

The /sharing/add_folder_member endpoint allows the members of a shared folder with owner or editor rights to add another member. We are required to enable the sharing.write permission for this endpoint to work.

Request parameters

This endpoint takes four parameters, which we can see in the table below.

Parameter Name

Description

Format/Value

Required

shared_folder_id

This takes the ID of the shared folder.

String

Yes

members

This is a parameter that defines a list of members to be added to a folder. Access level of owner is not allowed.

List of members

Yes

quiet

This defines if we should notify the member or not. The default value is False.

Boolean

No

custom_message

This is the message we want to send to the added member in their invitation.

String

No

Let’s add a member to a folder in the code below.

Press + to interact
import requests
import json
url = "https://api.dropboxapi.com/2/sharing/add_folder_member"
headers = {
    "Authorization": "Bearer {{TOKEN}}",
    "Content-Type": "application/json"
}
data = {
    "shared_folder_id": "{{FOLDER_ID}}",
    "members": [{
        "member":{".tag":"email",
        "email":"user_id@gmail.com"},
        "access_level":{".tag":"editor"}
        }]
}
r = requests.request("POST",url, headers=headers, data=json.dumps(data))
print(r)

In the code above, we see the following:

  • Lines 11–18: We wrap the data in the data object.
  • Line 12: This shows the ID of the shared folder, SharedFolder.
  • Lines 13–17: We define the members list, which includes the tag, email, and access_level of the specified member. We’ll replace the placeholder email address with the one we want to add to the folder.
  • Line 20: This is the request.
  • Line 21: We print the response.

Note: We can add multiple members in the members list as shown in the code block below.

{"member":
    {
        ".tag":"email",
        "email":"user_id_1@gmail.com"
    },
        "access_level":{".tag":"editor"}
}
{"member":
    {
        ".tag":"email",
        "email":"user_id_2@gmail.com"
    },
        "access_level":{".tag":"editor"}
}

Response

The successful execution of this code doesn’t return any value but will return the HTTP status code. Now, we’ll go to the location of the SharedFolder in our Dropbox dashboard, and we’ll notice that the “Who can access” column has two members now.

Accepting an invitation

The member we’ve added will get an email and device notification about the shared folder. Clicking on the device notification will take us to the folder, and it will ask if we want to add it to our Dropbox. Click the “Add to Dropbox” button.

Note: We assume that the added member is already registered on Dropbox. Otherwise, they’ll first need to sign up for a Dropbox account.