REST API for Documents

Create Folder Public Link

post

/documents/api/1.2/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

Supported Media Types

application/json
application/xml

Path Parameters

folderId: string

Globally unique identifier (GUID) for the folder.

The request body defines details of the create public link request. Bold indicates a required value.

Root Schema : PublicLinkBody

Type: object

The request body defines details of the create public link request. Bold indicates a required value.

Show Source

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.

{
    "description":"The request body defines details of the create public link request. <b>Bold</b> indicates a required value.",
    "properties":{
        "assignedUsers":{
            "type":"string",
            "description":"<p>The group of users who can use the link.</p><p><ul><li>Comma-separated list of users (any of user ID, login name, or email address).</li><li>@serviceinstance: Users with an account can access the resource with the privileges specified by the role.</li><li>@everybody: Any user can access the resource with the privileges specified by the role.</li></ul></p>"
        },
        "expirationTime":{
            "type":"string",
            "description":"<p>Date and time when the public link expires, in the form <code>yyyy-mm-ddThh:mm:ss</code>. <pre>For example, 2017-01-01T00:00:01.</pre><p></p>If you do not specify an expiration time, the link is valid until you delete the link.</p>"
        },
        "password":{
            "type":"string",
            "description":"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."
        },
        "linkName":{
            "type":"string",
            "description":"Name of the public link. Although the link name is optional, you can have only one unnamed public link for a resource."
        },
        "role":{
            "type":"string",
            "description":"<p>Access level for the shared item.</p><p><b>Note:</b></p><p>Although the default role is viewer, the API user&#39;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.</p><p>You can grant the specified user any standard role except manager or owner:<ul><li><b>Viewer:</b> Viewers can look at files and folders, but can&#39;t change things.</li><li><b>Downloader:</b> Downloaders can also download files and save them to their own computer.</li><li><b>Contributor:</b> Contributors can also modify files, update files, upload new files, and delete files.</li></ul></p>",
            "enum":[
                "viewer",
                "downloader",
                "contributor"
            ]
        }
    },
    "required":[
        "assignedUsers"
    ]
}

Example Request (application/json)

{
    "assignedUsers":"@serviceinstance",
    "expirationTime":"2016-01-01T00:00:01Z",
    "password":"MyPassword",
    "linkName":"MyLinkOne",
    "role":"contributor"
}

Response

Supported Media Types

application/json
application/xml

200 Response

The request was fulfilled.

Root Schema : PublicLinkCreateResponse

Type: object

The response body includes information about the newly created public link.

Show Source

errorCode(optional): string

An error code of zero (0) indicates no errors.
id(optional): string

Globally unique identifier (GUID) for the folder or file.

{
    "description":"The response body includes information about the newly created public link.",
    "type":"object",
    "allOf":[
        {
            "$ref":"#/definitions/PublicLinkDefinition"
        }
    ],
    "properties":{
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        },
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the folder or file."
        }
    }
}

Match All

Show Source

object PublicLinkDefinition

Public link information.

{
    "description":"The response body includes information about the newly created public link.",
    "type":"object",
    "allOf":[
        {
            "$ref":"#/definitions/PublicLinkDefinition"
        }
    ],
    "properties":{
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        },
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the folder or file."
        }
    }
}

Nested Schema : PublicLinkDefinition

Type: object

Public link information.

Show Source

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.

{
    "description":"Public link information.",
    "properties":{
        "linkID":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the public link."
        },
        "linkName":{
            "type":"string",
            "description":"Name of the public link."
        },
        "assignedUsers":{
            "type":"string",
            "description":"The group of users who can use the link."
        },
        "role":{
            "type":"string",
            "description":"Access level for the shared item.",
            "enum":[
                "viewer",
                "downloader",
                "contributor"
            ]
        },
        "password":{
            "type":"string",
            "description":"Password for the public link. Use a minimum of 8 characters and a maximum of 50 characters. Passwords are case-sensitive."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>publiclink</code>."
        },
        "createdTime":{
            "type":"string",
            "description":"Date and time when the public link was created."
        },
        "expirationTime":{
            "type":"string",
            "description":"Date and time when the public link expires."
        },
        "lastModifiedTime":{
            "type":"string",
            "description":"Date and time when the public link was last modified."
        },
        "ownedBy":{
            "$ref":"#/definitions/User"
        }
    }
}

Nested Schema : User

Type: object

User information

Show Source

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.

{
    "description":"User information",
    "properties":{
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the user."
        },
        "displayName":{
            "type":"string",
            "description":"The display name for the user."
        },
        "loginName":{
            "type":"string",
            "description":"The login name for the user."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>user</code>."
        }
    }
}

Example Response (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"
}

400 Response

Request parameters are not formatted correctly.

403 Response

Forbidden if the user does not have read permission.

404 Response

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",
	"loginName": "userAALoginName",
	"id": "U0EAA20910FAF3052ACB79E4T00000000001",
	"type": "user"
    },
    "role": "contributor",
    "type": "publiclink"
}

Example 2

The following example does not create a public link because MyLinkDuplicate is already created for the specified folder ID.

POST .../publiclinks/folder/F42591255E9BED0FB76D1DC645B3E9DD6490E298CA02

Request Header

None.

Request Body

{
	"assignedUsers": "@everybody",
	"linkName": "MyLinkDuplicate",
	"role": "viewer"
}

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": "F42591255E9BED0FB76D1DC645B3E9DD6490E298CA02",
    "linkName": "MyLinkDuplicate",
    "role": "viewer",
    "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/folder/F42591255E9BED0FB76D1DC645B3E9DD6490E298CA02

Request Header

None.

Request Body

{
	"linkName": "MyLink2",
	"role": "viewer"
}

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": "F42591255E9BED0FB76D1DC645B3E9DD6490E298CA02",
    "linkName": "MyLink2",
    "role": "viewer",
    "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 folder ID does not exist.

POST ...publiclinks/folder/F42551255E9BED0FB76D1DC645B3E9DD6490E298CA02

Request Header

None.

Request Body

{
	"assignedUsers": "@everybody",
	"linkName": "MyLink4",
	"role": "viewer"
}

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "assignedUsers": "@everybody",
    "errorCode": "-16",
    "errorKey": "!csUnableToCreateSharedLink!csSecurityValidationFailed!csFldDoesNotExist,F42551255E9BED0FB76D1DC645B3E9DD6490E298CA02!csUnprivilegedSystemError",
    "errorMessage": "Sorry, but we couldn't create a link to this content. Please try again later. Security validation failed. 'F42551255E9BED0FB76D1DC645B3E9DD6490E298CA02' does not exist. The error was caused by an internally generated issue. The error has been logged.",
    "errorType": "publiclink",
    "id": "F42551255E9BED0FB76D1DC645B3E9DD6490E298CA02",
    "linkName": "MyLink4",
    "role": "viewer",
    "title": "Sorry, but we couldn't create a link to this content. Please try again later. Security validation failed. 'F42551255E9BED0FB76D1DC645B3E9DD6490E298CA02' 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/folder/F42551255E9BED0FB76D1DC645B3E9DD6490E298CA02

Request Header

None.

Request Body

{
	"assignedUsers": "invalid",
	"linkName": "MyLink5",
	"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": "F42591255E9BED0FB76D1DC645B3E9DD6490E298CA02",
    "linkName": "MyLink5",
    "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"
}