Share Folder or Collection

post

/documents/api/1.1/shares/{folderId}

Share a specified folder or collection with a specified user.

For information about finding users, see Users REST Endpoints.

When you share folders or collections, you control the permissions each person has for the folder and its files or collection and its assets by assigning a role to the person. The different roles determine what a person can do with a shared folder or collection.

• Viewer: Viewers can look at the contents of a folders or collection but can't change things.
• Downloader: Downloaders can also download files or assets and save them to their own computers.
• Contributor: Contributors can also modify, update, upload, and delete files or assets. Contributors can also get metadata values, get metadata definitions, and set values for metadata already assigned by the folder or collection owner.
• Manager: Managers have all the privileges of the other roles and can add or remove other people as members.

• Request
• Response
• Examples

Request

Supported Media Types

• application/json
• application/xml

Path Parameters

folderId

Type: string

Required: true

Globally unique identifier (GUID) for the folder or collection. For sharing the user's home folder, the value for folderId is self

.

Body Parameter

The request body defines details of the share request. Bold indicates a required value.

Root Schema : ShareFolderBody

The request body defines details of the share folder or collection request. Bold indicates a required value.

Properties

currentOnly

Type: string

Apply the share to the specified folder only (1) or to the specified folder and all nested folders (0). By default, this option is not enabled (0).

message

Type: string

Optional message sent to the user.

role

Type: string

Required: true

Allowed Values: [ "viewer", "downloader", "contributor", "manager" ]

Access level for the shared item:

• viewer: Viewers can look at files, folders, and assets but can't change things.
• downloader: Downloaders can also download files and assets and save them to their own computers.
• contributor: Contributors can also modify, update, upload, and delete files or assets.
• manager: Managers have all the privileges of the other roles and can add or remove other people as members.

userID

Type: string

Required: true

Globally unique identifier (GUID) for the user.

Example application/json

{
    "userID":"U7ECC74059E0FEDFEC66BF5AT00000000001",
    "role":"manager",
    "message":"Granting you shared access to this folder."
}

Response

Supported Media Types

• application/json
• application/xml

200 Response

The request was fulfilled.

Body

The response body includes share information along with user information.

Root Schema : ShareFolderResponse

The response body includes share information along with user information.

Properties

errorCode

Type: string

An error code of zero (0) indicates no errors.

id

Type: string

Globally unique identifier (GUID) for the folder or collection.

role

Type: string

Access level for the shared item.

type

Type: string

Item type share.

user

Type: object User

Additional Properties Allowed:

User information

Nested Schema : User

User information

Properties

displayName

Type: string

The display name for the user.

id

Type: string

Globally unique identifier (GUID) for the user.

type

Type: string

Item type user.

Example application/json

{
    "id":"F1321DC48E3B123D02DBEE88T0000000000100000001",
    "role":"manager",
    "type":"share",
    "errorCode":"0",
    "user":{
        "id":"U7ECC74059E0FEDFEC66BF5AT00000000001",
        "displayName":"User BB",
        "type":"user"
    }
}

400 Response

Request parameters are not formatted correctly.

403 Response

Forbidden if the user does not have read permission.

404 Response

Folder ID is not found.

Examples

The following example grants manager-level access to the specified folder.

POST .../shares/F1321DC48E3B123D02DBEE88T0000000000100000001

Request Header

None.

Request Body

{
    "userID": "U7ECC74059E0FEDFEC66BF5AT00000000001",
    "role": "manager",
    "message": "granting you shared access to this folder"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0",
    "id": "F1321DC48E3B123D02DBEE88T0000000000100000001",
    "role": "manager",
    "type": "share",
    "user": {
        "displayName": "User BB",
        "id": "U7ECC74059E0FEDFEC66BF5AT00000000001",
        "type": "user"
    }
}

Example 2

The following example shares a collection with another user.

POST .../shares/FB0D96BA354156E495F5475B45B3E9DD649055F5640B

Request Header

None.

Request Body

{
    "userID": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
    "role": "manager",
    "message": "granting you shared access to this collection"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0",
    "id": "FB0D96BA354156E495F5475B45B3E9DD649055F5640B",
    "role": "manager",
    "type": "share",
    "user": {
        "displayName": "cecsuser4",
        "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
        "loginName": "tenant1.cecsuser4",
        "type": "user"
    }
}