1. REST API for Documents
  2. Tasks
  3. Shares

Share Folder or Collection

post

/documents/api/1.2/shares/{folderId}

Share a specified folder or collection with specified user(s) and/or group(s). When you share folders or collections, you control the permissions each person/group has for the folder and its files or collection and its assets by assigning a role to the person/group. The different roles determine what a person/group 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

Supported Media Types
Path Parameters

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

    .
Body ()
The request body defines details of the share request. Bold indicates a required value.
Root Schema : ShareFolderBody
Type: object
The request body defines details of the share folder or collection request. Bold indicates a required value.
Show Source
  • Optional message sent to the user.
  • 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.

  • Globally unique identifier (GUID) for the user, login name of the user, GUID for the group or a comma-separated list of the above (no more than 1000 total IDs).
Example Request (application/json)
{
    "userID":"U7ECC74059E0FEDFEC66BF5AT00000000001",
    "role":"manager",
    "message":"Granting you shared access to this folder."
}
Back to Top

Response

Supported Media Types

200 Response

The request was fulfilled.

Body ()
Root Schema : ShareFolderResponse
Type: object
The response body includes share information along with user(s) or group(s) information.
Show Source
Nested Schema : members
Type: array
Users or groups with whom the folder is being shared in the current request.
Show Source
Nested Schema : User
Type: object
User information
Show Source
Nested Schema : items
Type: object
Show Source
Example Response (application/json)
{
    "errorCode":"0",
    "id":"F1321DC48E3B123D02DBEE88T0000000000100000001",
    "members":[
        {
            "id":"U7ECC74059E0FEDFEC66BF5AT00000000001",
            "displayName":"User BB",
            "type":"user",
            "isSuccessful":"1"
        }
    ],
    "role":"manager",
    "type":"share",
    "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 or there was a problem with one or more supplied users or groups.

404 Response

Folder ID is not found.

Back to Top

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",
    "members":[
        {
            "id":"U7ECC74059E0FEDFEC66BF5AT00000000001",
            "displayName":"User CC",
            "type":"user",
            "isSuccessful":"1"
        }
    ],
    "role": "manager",
    "type": "share",
    "user": {
        "displayName": "User CC",
        "loginName": "userCCLoginName",
        "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",
    "members":[
        {
            "id":"U5C4D5FCE14F2B44946FA74745B3E9DD6490",
            "displayName":"User DD",
            "type":"user",
            "isSuccessful":"1"
        }
    ],
    "role": "manager",
    "type": "share",
    "user": {
	      "displayName": "User DD",
	      "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
	      "loginName": "userDDLoginName",
	      "type": "user"
    }
}

Example 3

The following example attempts to share a folder with the viewer role, but an error is returned because the user already has higher access to the folder. 

PUT .../shares/F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F

Request Header

None.

Request Body

{
    "userID": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
    "role": "viewer",
    "message": "granting you shared access"
}

HTTP Status Code

HTTP_STATUS = 403

JSON Response

{
    "errorCode": "-1",
    "errorKey": "!csUserAlreadyHasAccessToFolder,User DD,f2",
    "errorMessage": "User 'UserAA' already has access to folder 'f2' with identical or higher privileges.",
    "errorType": "share",
    "id": "F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F",
    "members":[
        {
            "id":"U5C4D5FCE14F2B44946FA74745B3E9DD6490",
            "displayName":"User DD",
            "type":"user",
            "isSuccessful":"0"
        }
    ],
    "role": "viewer",
    "title": "User 'User DD' already has access to folder 'f2' with identical or higher privileges.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "user": {
	"displayName": "User DD",
	"id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
	"loginName": "userDDLoginName",
	"type": "user"
    }
}

Example 4

The following example returns an error because the userID parameter is missing from the request body. 

PUT .../shares/F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F

Request Header

None.

Request Body

{
    "role": "viewer",
    "message": "granting you shared access"
}

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "errorCode": "-97",
    "errorKey": "!csUnableToShareFolder!csRequiredServiceParameterMissing,dUserID,SHARE_FOLDER",
    "errorMessage": "Failed to share folder. Parameter 'dUserID' required by service SHARE_FOLDER is missing.",
    "errorType": "share",
    "id": "F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F",
    "role": "viewer",
    "title": "Failed to share folder. Parameter 'dUserID' required by service SHARE_FOLDER is missing.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 5

The following example returns an error because the folder (or collection) ID is invalid.

PUT .../shares/F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F

Request Header

None.

Request Body

{
    "userID": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
    "role": "manager"
}

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "errorCode": "-16",
    "errorKey": "!csUnableToShareFolder!csSecurityValidationFailed!csFldDoesNotExist,F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F!csUnprivilegedSystemError",
    "errorMessage": "Failed to share folder. Security validation failed. 'F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F' does not exist. The error was caused by an internally generated issue. The error has been logged.",
    "errorType": "share",
    "id": "F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F",
    "role": "manager",
    "title": "Failed to share folder. Security validation failed. 'F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F' does not exist. The error was caused by an internally generated issue. The error has been logged.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "user": {
        "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
        "type": "user"
    }
}

Example 6

The following example shares a folder with two users (using user GUID and login name) and a group.

Request Header

None.

Request Body

{
    "userID": "U92A91A29A46767692583BCCCC4A88C356D9,JohnSmith,GS18003",
    "role": "manager",
    "message": "granting you shared access"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0",
    "id": "F6ED064539F10B076BC0F8E19AD1D511040A6D384E90",
    "members": [
        {
            "id": "U92A91A29A46767692583BCCCC4A88C356D9",
            "displayName": "David Lee",
            "type": "user",
            "isSuccessful": "1"
        },
        {
            "id": "JohnSmith",
            "displayName": "John Smith",
            "type": "user",
            "isSuccessful": "1"
        },
        {
            "id": "GS18003",
            "displayName": "Sales Group",
            "type": "group",
            "isSuccessful": "1"
        }
    ],
    "role": "manager",
    "type": "share",
    "user": {
        "id": "U92A91A29A46767692583BCCCC4A88C356D9,JohnSmith,GS18003",
        "type": "user"
    }
}
Back to Top