Create File Public Link
/documents/api/1.1/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
-
Type:
string
Required:true
Globally unique identifier (GUID) for the file.
- 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":"MyFileLinkOne",
"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":"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"
}
Request parameters are not formatted correctly.
Forbidden if the user does not have read permission.
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", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "role": "contributor", "type": "publiclink" }