Create Folder Public Link
/documents/api/1.1/publiclinks/folder/{folderId}
Create a public link for a specified folder.
A public link allows specific users access to the requested folder, whether they have an account or not.
Note:
To create a public link, the requester must have admin privileges for the folder or file. That is, the requester must be the owner or have the manager role.
Request
- application/json
- application/xml
- folderId
-
Type:
string
Required:true
Globally unique identifier (GUID) for the folder.
- assignedUsers
-
Type:
string
Required:true
The group of users who can use the link.
- Comma-separated list of users (any of user ID, login name, or email address).
- @serviceinstance: Users with an account can access the resource with the privileges specified by the role.
- @everybody: Any user can access the resource with the privileges specified by the role.
- expirationTime
-
Type:
string
Date and time when the public link expires, in the form
yyyy-mm-ddThh:mm:ss
.For example, 2017-01-01T00:00:01.
If you do not specify an expiration time, the link is valid until you delete the link. - linkName
-
Type:
string
Name of the public link. Although the link name is optional, you can have only one unnamed public link for a resource. - password
-
Type:
string
Password for the public link. Use a minimum of 8 characters and a maximum of 50 characters. If you do not specify a password, no password is required to use the link. - role
-
Type:
string
Allowed Values:[ "viewer", "downloader", "contributor" ]
Access level for the shared item.
Note:
Although the default role is viewer, the API user's preference setting for the default role for public links can override this default with a different value. It is best practice to explicitly set the role with the service call.
You can grant the specified user any standard role except manager or owner:
- Viewer: Viewers can look at files and folders, but can't change things.
- Downloader: Downloaders can also download files and save them to their own computer.
- Contributor: Contributors can also modify files, update files, upload new files, and delete files.
Example application/json
{
"assignedUsers":"@serviceinstance",
"expirationTime":"2016-01-01T00:00:01Z",
"password":"MyPassword",
"linkName":"MyLinkOne",
"role":"contributor"
}
Response
- application/json
- application/xml
The request was fulfilled.
object
- errorCode
-
Type:
string
An error code of zero (0) indicates no errors. - id
-
Type:
string
Globally unique identifier (GUID) for the folder or file.
-
Type:
object
PublicLinkDefinitionAdditional Properties Allowed:Public link information.
- assignedUsers
-
Type:
string
The group of users who can use the link. - createdTime
-
Type:
string
Date and time when the public link was created. - expirationTime
-
Type:
string
Date and time when the public link expires. - lastModifiedTime
-
Type:
string
Date and time when the public link was last modified. - linkID
-
Type:
string
Globally unique identifier (GUID) for the public link. - linkName
-
Type:
string
Name of the public link. - ownedBy
-
Type:
object
UserAdditional Properties Allowed:User information - password
-
Type:
string
Password for the public link. Use a minimum of 8 characters and a maximum of 50 characters. Passwords are case-sensitive. - role
-
Type:
string
Allowed Values:[ "viewer", "downloader", "contributor" ]
Access level for the shared item. - type
-
Type:
string
Item typepubliclink
.
- displayName
-
Type:
string
The display name for the user. - id
-
Type:
string
Globally unique identifier (GUID) for the user. - type
-
Type:
string
Item typeuser
.
Example application/json
{
"linkID":"LF906748A021ACD714CABC82T0000000000100000001",
"linkName":"MyLinkOne",
"assignedUsers":"@serviceinstance",
"role":"contributor",
"type":"publiclink",
"createdTime":"2015-06-10T16:01:44Z",
"expirationTime":"2016-01-01T00:00:01Z",
"lastModifiedTime":"2015-06-10T16:01:44Z",
"ownedBy":{
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"displayName":"User AA",
"type":"user"
},
"errorCode":"0",
"id":"FBE1117A270E747BB1D95024T0000000000100000001"
}
Request parameters are not formatted correctly.
Forbidden if the user does not have read permission.
Folder ID is not found.
Examples
The following example grants contributor-level access to all account holders for the Content and Experience instance that hosts the specified folder.
POST .../publiclinks/folder/FBE1117A270E747BB1D95024T0000000000100000001
Request Header
None.
Request Body
{ "assignedUsers": "@serviceinstance", "expirationTime": "2016-01-01T00:00:01Z", "password": "MyPassword", "linkName": "MyLinkOne", "role": "contributor" }
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "assignedUsers": "@everybody", "createdTime": "2015-06-10T16:01:44Z", "errorCode": "0", "expirationTime": "2016-01-01T00:00:01Z", "id": "FBE1117A270E747BB1D95024T0000000000100000001", "lastModifiedTime": "2015-06-10T16:01:44Z", "linkID": "LF906748A021ACD714CABC82T0000000000100000001", "linkName": "MyLinkOne", "ownedBy": { "displayName": "User AA", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "role": "contributor", "type": "publiclink" }