Create File Public Link
/documents/api/1.2/publiclinks/file/{fileId}
Create a public link for a specified file.
A public link allows specific users access to the requested file, 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
-
fileId: string
Globally unique identifier (GUID) for the file.
object
-
assignedUsers:
string
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(optional):
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(optional):
string
Name of the public link. Although the link name is optional, you can have only one unnamed public link for a resource.
-
password(optional):
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(optional):
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.
{
"assignedUsers":"@serviceinstance",
"expirationTime":"2016-01-01T00:00:01Z",
"password":"MyPassword",
"linkName":"MyFileLinkOne",
"role":"contributor"
}
Response
- application/json
- application/xml
200 Response
The request was fulfilled.
object
-
errorCode(optional):
string
An error code of zero (0) indicates no errors.
-
id(optional):
string
Globally unique identifier (GUID) for the folder or file.
-
object
PublicLinkDefinition
Public link information.
object
-
assignedUsers(optional):
string
The group of users who can use the link.
-
createdTime(optional):
string
Date and time when the public link was created.
-
expirationTime(optional):
string
Date and time when the public link expires.
-
lastModifiedTime(optional):
string
Date and time when the public link was last modified.
-
linkID(optional):
string
Globally unique identifier (GUID) for the public link.
-
linkName(optional):
string
Name of the public link.
-
ownedBy(optional):
object User
User information
-
password(optional):
string
Password for the public link. Use a minimum of 8 characters and a maximum of 50 characters. Passwords are case-sensitive.
-
role(optional):
string
Allowed Values:
[ "viewer", "downloader", "contributor" ]
Access level for the shared item. -
type(optional):
string
Item type
publiclink
.
object
-
displayName(optional):
string
The display name for the user.
-
id(optional):
string
Globally unique identifier (GUID) for the user.
-
loginName(optional):
string
The login name for the user.
-
type(optional):
string
Item type
user
.
{
"linkID":"LDFD004B846DB106DB8B2906T0000000000100000001",
"linkName":"MyFileLinkOne",
"assignedUsers":"@everybody",
"role":"contributor",
"type":"publiclink",
"createdTime":"2015-06-10T16:13:19Z",
"expirationTime":"2017-01-01T00:00:01Z",
"lastModifiedTime":"2015-06-10T16:13:19Z",
"ownedBy":{
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"displayName":"User AA",
"type":"user"
},
"errorCode":"0",
"id":"D1E1E9F089AC1EF8481E5B94T0000000000100000001"
}
400 Response
Request parameters are not formatted correctly.
403 Response
Forbidden if the user does not have read permission.
404 Response
File ID is not found.
Examples
The following example grants contributor-level access to all users for the specified file, whether they have an account or not.
POST .../publiclinks/file/D1E1E9F089AC1EF8481E5B94T0000000000100000001
Request Header
None.
Request Body
{ "assignedUsers": "@everybody", "expirationTime": "2016-01-01T00:00:01Z", "password": "MyPassword", "linkName": "MyFileLinkOne", "role": "contributor" }
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "assignedUsers": "@everybody", "createdTime": "2015-06-10T16:13:19Z", "errorCode": "0", "expirationTime": "2017-01-01T00:00:01Z", "id": "D1E1E9F089AC1EF8481E5B94T0000000000100000001", "lastModifiedTime": "2015-06-10T16:13:19Z", "linkID": "LDFD004B846DB106DB8B2906T0000000000100000001", "linkName": "MyFileLinkOne", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "role": "contributor", "type": "publiclink" }
Example 2
The following example does not create a public link because MyFileLinkDuplicate
is already created for the specified file ID.
POST .../publiclinks/file/D88BB10A715A62A28C7A64B545B3E9DD6490E298CA02
Request Header
None.
Request Body
{ "assignedUsers": "@everybody", "expirationTime": "2019-01-01T00:00:01Z", "password": "MyPassword", "linkName": "MyFileLinkDuplicate", "role": "contributor" }
HTTP Status Code
HTTP_STATUS = 409
JSON Response
{ "errorCode": "-17", "errorKey": "!csUnableToCreateSharedLink!csLinkWithSameNameExists", "errorMessage": "Sorry, but we couldn't create a link to this content. Please try again later. Sorry, we cannot create a public link because there is already a link with that name. Make sure to use a unique name when creating a public link.", "errorType": "publiclink", "id": "D88BB10A715A62A28C7A64B545B3E9DD6490E298CA02", "linkName": "MyFileLinkDuplicate", "role": "contributor", "title": "Sorry, but we couldn't create a link to this content. Please try again later. Sorry, we cannot create a public link because there is already a link with that name. Make sure to use a unique name when creating a public link.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 3
The following example does not create a public link because the required assignedUsers
parameter is missing from the request body.
POST .../publiclinks/file/D773CC8078273C897108399345B3E9DD64907CA0D19F
Request Header
None.
Request Body
{ "linkName": "MyFileLink3", "role": "contributor" }
HTTP Status Code
HTTP_STATUS = 400
JSON Response
{ "errorCode": "-97", "errorKey": "!csUnableToCreateSharedLink!csRequiredServiceParameterMissing,dAssignedUsers,CREATE_SHARED_LINK", "errorMessage": "Sorry, but we couldn't create a link to this content. Please try again later. Parameter 'dAssignedUsers' required by service CREATE_SHARED_LINK is missing.", "errorType": "publiclink", "id": "D773CC8078273C897108399345B3E9DD64907CA0D19F", "linkName": "MyFileLink3", "role": "contributor", "title": "Sorry, but we couldn't create a link to this content. Please try again later. Parameter 'dAssignedUsers' required by service CREATE_SHARED_LINK is missing.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 4
The following example does not create a public link because the specified file ID does not exist.
POST .../publiclinks/file/D88BB54A715A62A28C7A64B545B3E9DD6490E298CA02
Request Header
None.
Request Body
{ "assignedUsers": "@everybody", "linkName": "MyFileLink4", "role": "viewer" }
HTTP Status Code
HTTP_STATUS = 404
JSON Response
{ "assignedUsers": "@everybody", "errorCode": "-16", "errorKey": "!csUnableToCreateSharedLink!csSecurityValidationFailed!csFldDoesNotExist,D88BB54A715A62A28C7A64B545B3E9DD6490E298CA02!csUnprivilegedSystemError", "errorMessage": "Sorry, but we couldn't create a link to this content. Please try again later. Security validation failed. 'D88BB54A715A62A28C7A64B545B3E9DD6490E298CA02' does not exist. The error was caused by an internally generated issue. The error has been logged.", "errorType": "publiclink", "id": "D88BB54A715A62A28C7A64B545B3E9DD6490E298CA02", "linkName": "MyFileLink4", "role": "viewer", "title": "Sorry, but we couldn't create a link to this content. Please try again later. Security validation failed. 'D88BB54A715A62A28C7A64B545B3E9DD6490E298CA02' 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" }
Example 5
The following example does not create a public link because the user specified for assignedUsers
does not exist.
POST .../publiclinks/file/D425BBE926A9DED2A822B6C245B3E9DD64907CA0D19F
Request Header
None.
Request Body
{ "assignedUsers": "invalid", "linkName": "MyFileLink55", "role": "viewer" }
HTTP Status Code
HTTP_STATUS = 404
JSON Response
{ "errorCode": "-25", "errorKey": "!csUnableToCreateSharedLink!csSharedLinkUserNotFound,invalid", "errorMessage": "Sorry, but we couldn't create a link to this content. Please try again later. User 'invalid' doesn't exist.", "errorType": "publiclink", "id": "D425BBE926A9DED2A822B6C245B3E9DD64907CA0D19F", "linkName": "MyFileLink55", "role": "viewer", "title": "Sorry, but we couldn't create a link to this content. Please try again later. User 'invalid' doesn't exist.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }