Changing Share Options

You can use the share call to change the share options of a folder.

Sample URL

https://hostname:port/context/rest/v2/documents/share/{id}

Method

POST

Parameters

Parameter Description
id The ID of the document.

This parameter is required if the path parameter is not present.

path The fully qualified File Share path name.

This parameter is required if the id parameter is not present; otherwise, it is ignored.

expirationDate Optional.

the share expiration date.

The format is yyyy-mm-dd. If it is left blank, the share never expires.

expirationAction

This parameter is required if the expirationDate parameter is present.

The valid values are add and delete.
  • add: means to add an expiration date.
  • delete : means to remove the existing expiration date.

The default value is add when the expirationDate parameter is present; otherwise, it has no default value.

replaceUsers Optional.
The valid values are true and false.
  • true: means to replace the existing collaborators with the new ones.
  • false: means to add, delete, or update collaborators.
The default value is false.
user Optional.
The format is <action>;<user id><user type>. The valid actions are add and delete.
  • add: means to add or update a collaborator.
  • delete : means to remove the collaborator.
The valid user types are O for Owner, E for Editor, and V for Viewer. If the action is Delete, the user type could be empty.
message Optional.

A message in HTML format.

The default value is a system generated message.

SendToSelf Optional.

If the value is yes, send a copy of the email to the logged-on user.

Note:
  • Users cannot remove themselves from the collaborator list. They should use the decline call instead.
  • A document must have at least one owner.
  • The original owner has access to the document until explicitly removed.

  • Sample request to add a user as an editor: 

    replaceUsers=false 
user=add;UserId;E

  • Sample request to delete a collaborator: 

    replaceUsers=false
 user=delete;UserId1

  • Sample request to remove all existing collaborators and add new ones: 

    replaceUsers=true
user=add;UserId1;O
user=add;UserId2;E
user=add;UserId3;V

  • Sample request to remove all collaborators so only the original owner can access the document: 

    replaceUsers=true

  • Sample request to add or change the share expiration date: 

    expirationDate=2013-12-31

  • Sample request to delete the share expiration date so the share will never expire: 

    expirationDate=

Response

HTTP Status Code Description
406 Not Acceptable. The document cannot be shared because it is not a folder.
409 Conflict. The document cannot be shared because failed to verify that is not already shared, user does not exist, and other conflicts.

Example:

{"users":"O:admin:A:admin;N:DBUser:U:DBUser","dateModified":0,"shareExpiration":1395028799469,"type":"D","lastUpdatedOn":1394817031577, "size":0,"message":"","id":"143500000003","createdOn":1394041226577,"latestVersion":39,"shareId":"143500000003", "createdBy":"admin","name":"A"}

Format of the Users field is <user type>:<user id>:<share status code><displayable user id>.

The share status codes are as follows:
  • A: means the user has accepted the share invitation.
  • D: means the user has declined.
  • P: means the user has not accepted or declined.
  • U: means the user has been removed.