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 endpoint is used to create a shared link to a folder. This endpoint requires us to enable the sharing.write permission to do this task. Sometimes the sharing process can take a little long. If the process is finished within the wait time of the API call, it will return the response of the process. Otherwise, it will treat the process as asynchronous and return the ID of the asynchronous process.

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

Format/Value

Required

Description

path

String

Yes

Path of the folder that we want to share. The endpoint will create a new folder if it isn't found in the specified directory.

acl_update_policy

The value can either be owner or editor.

No

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

force_async

Boolean

No

Defines that the shared operation must be asynchronous. Default value is False.

actions

change_options, display_viewer_info,

edit_contents,

enable_viewer_info, invite_viewer_no_comment


No

Defines a list of actions that an authenticated user can do with the folder. Some of the action values are mentioned in the next field.

link_settings

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

No

States the settings of the shared link.

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

Press + to interact
// Define import libraries here
import fetch from 'node-fetch';
// Define API key here
const token = '{{TOKEN}}'
// Define endpoint URL here
const endpointUrl = new URL('https://api.dropboxapi.com/2/sharing/share_folder');
// Define Header Parameters here
const headerParameters = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json',
};
// Define Body Parameters here
const bodyParameters = JSON.stringify({
  path: "/home/TestFolder"
});
// Set the API call options
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
// Function to make the API call
async function shareFolder() {
  try {
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Call function to make the API call
shareFolder();

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 do the following:

  • Line 2: We import the fetch library that we need to use in our code from node-fetch.
  • Line 5: We get the value for TOKEN to use for authentication.
  • Line 8: We define the request URL.
  • Lines 11–14: We define the headers of the fetch request. It includes the authorization and the type of content, which is application/json in most cases.
  • Lines 17–19: We define the bodyParameters of the fetch request.
  • Lines 22–26: We set the API call options.
  • Lines 29–38: We create a function to make the API call. It will try to get the response and will pass the response to the custom function printResponse; otherwise, it will catch the error and will pass it to the custom function printError.
  • Line 41: We call the function shareFolder to make the API call.

Response

We’ll notice that a shared folder with the name of TestFolder has been created and can be found in the shared tab, 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 the operation is asynchronous. This ID will be used to check the status of the operation.

Press + to interact
Shared folder TestFolder is created
Shared folder TestFolder is created

In the table below, we show some of the response fields of the share_folder endpoint.

Fields

Format

Description

access_type

String

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

name

String

Name of the folder.

policy

String

Provides all of the policy types related to this shared folder.

preview_url

String

This value is used to access the shared folder in a web preview.

shared_folder_id

String

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

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 18 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
// Define import libraries here
import fetch from 'node-fetch';
// Define API key here
const token = '{{TOKEN}}'
// Define endpoint URL here
const endpointUrl = new URL('https://api.dropboxapi.com/2/sharing/check_job_status');
// Define Header Parameters here
const headerParameters = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json',
};
// Define Body Parameters here
const bodyParameters = JSON.stringify({
  "async_job_id": "{async_job_id}"
});
// Set the API call options
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
// Function to make the API call
async function getStatus() {
  try {
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Call function to make the API call
getStatus();

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’re required to enable the sharing.write permission for this endpoint to work.

Request parameters

This endpoint has two required and two optional parameters, which we can see in the table below:

Parameter Name

Format/Value

Required

Description

shared_folder_id

String

Yes

ID of the shared folder.

members

List of members

Yes

Defines a list of members to be added to a folder. Access level of owner is not allowed.

quiet

Boolean

No

Defines if we should notify the member or not. Default value is False.

custom_message

String

No

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

Let’s add a member to a folder in the code below. The email of the member is user_id@gmail.com, and they will have editor access.

Press + to interact
// Define import libraries here
import fetch from 'node-fetch';
// Define API key here
const token = '{{TOKEN}}'
// Define endpoint URL here
const endpointUrl = new URL('https://api.dropboxapi.com/2/sharing/add_folder_member');
// Define Header Parameters here
const headerParameters = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json',
};
// Define Body Parameters here
const bodyParameters = JSON.stringify({
  "shared_folder_id": "{{FOLDER_ID}}",
    "members": [{
        "member":{".tag":"email",
        "email":"user_id@gmail.com"},
        "access_level":{".tag":"editor"}
        }]
});
// Set the API call options
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
// Function to make the API call
async function addMember() {
  try {
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    console.log('status code: ', response.status);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Call function to make the API call
addMember();

In the code above, we do the following:

  • Line 2: We import the fetch library that we need to use in our code from node-fetch.
  • Line 5: We get the value for TOKEN to use for authentication.
  • Line 8: We define the request URL.
  • Lines 11–14: We define the headers of the fetch request. It includes the authorization and the type of content, which is application/json in most cases.
  • Lines 17–24: We define the bodyParameters of the fetch request.
  • Lines 27–31: We set the API call options.
  • Lines 34–43: We create a function to make the API call. It will try to get the response and will pass the response to the custom function printResponse; otherwise, it will catch the error and will pass it to the custom function printError.
  • Line 46: We call the function addMember to make the API call.

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 added member will get an email and device notification about the shared folder. Clicking on the device notification will take them to the folder and ask if they want to add it to their Dropbox. They can click the “Add to Dropbox” button to do so.

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