Jump to

• Request
• Response
• Examples

Get File Public Link

get

/documents/api/1.2/publiclinks/file/{fileId}

Return a list of the public links for a specified file.

Request

Supported Media Types

• application/json
• application/xml

Path Parameters

• fileId: string
  Globally unique identifier (GUID) for the file.

Back to Top

Response

Supported Media Types

• application/json
• application/xml

200 Response

The request was fulfilled.

Body ()

Root Schema : FileLinksResponse

Type: object

The response body includes information about public links defined for the specified file.

Show Source

• count(optional): string
  The number of items listed on the page.
• errorCode(optional): string
  An error code of zero (0) indicates no errors.
• id(optional): string
  Globally unique identifier (GUID) for the file.
• items(optional): array items
  List of public links.
• type(optional): string
  Item type file.

{
    "description":"The response body includes information about public links defined for the specified file.",
    "properties":{
        "count":{
            "type":"string",
            "description":"The number of items listed on the page."
        },
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the file."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>file</code>."
        },
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        },
        "items":{
            "type":"array",
            "description":"List of public links.",
            "items":{
                "$ref":"#/definitions/PublicLinkDefinition"
            }
        }
    }
}

Nested Schema : items

Type: array

List of public links.

Show Source

• Array of: object PublicLinkDefinition
  Public link information.

{
    "type":"array",
    "description":"List of public links.",
    "items":{
        "$ref":"#/definitions/PublicLinkDefinition"
    }
}

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)

{
    "count":"2",
    "id":"D1E1E9F089AC1EF8481E5B94T0000000000100000001",
    "type":"file",
    "errorCode":"0",
    "items":[
        {
            "linkID":"LDFD004B846DB106DB8B2906T0000000000100000001",
            "linkName":"MyFileLinkOne",
            "assignedUsers":"@everybody",
            "role":"contributor",
            "type":"publiclink",
            "createdTime":"2015-06-10T16:13:19Z",
            "lastModifiedTime":"2015-06-10T16:13:19Z",
            "expirationTime":"2017-01-01T00:00:01Z",
            "ownedBy":{
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "displayName":"User AA",
                "type":"user"
            }
        },
        {
            "linkID":"LF5E5F73A444FFB8924EF8ACT0000000000100000001",
            "linkName":"MyFileLinkTwo",
            "assignedUsers":"@everybody",
            "role":"contributor",
            "type":"publiclink",
            "createdTime":"2015-06-10T16:17:11Z",
            "lastModifiedTime":"2015-06-10T16:17:11Z",
            "ownedBy":{
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "displayName":"User AA",
                "type":"user"
            }
        }
    ]
}

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.

Back to Top

Examples

The following example returns information about public links defined for the specified file.

GET .../publiclinks/file/D1E1E9F089AC1EF8481E5B94T0000000000100000001

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "2",
    "errorCode": "0",
    "id": "D1E1E9F089AC1EF8481E5B94T0000000000100000001",
    "type": "file",
    "items": [
        {
            "type": "publiclink",
            "linkID": "LDFD004B846DB106DB8B2906T0000000000100000001",
            "linkName": "MyFileLinkOne",
            "ownedBy": {
		            "displayName": "User AA",
		            "loginName": "userAALoginName",
		            "id": "U0EAA20910FAF3052ACB79E4T00000000001",
		            "type": "user"
            },
            "role": "contributor",
            "assignedUsers": "@everybody",
            "createdTime": "2015-06-10T16:13:19Z",
            "lastModifiedTime": "2015-06-10T16:13:19Z",
            "expirationTime": "2017-01-01T00:00:01Z"
        },
        {
            "type": "publiclink",
            "linkID": "LDF81E2BEDFDC8D8B3D2FB65T0000000000100000001",
            "linkName": "MyFileLinkTwo",
            "ownedBy": {
		            "displayName": "User AA",
		            "loginName": "userAALoginName",
		            "id": "U0EAA20910FAF3052ACB79E4T00000000001",
		            "type": "user"
            },
            "role": "contributor",
            "assignedUsers": "@everybody",
            "createdTime": "2015-06-10T16:17:11Z",
            "lastModifiedTime": "2015-06-10T16:17:11Z"
        }
    ]
}

Example 2

The following example returns returns succesfully, but the file ID has no public links.

GET .../publiclinks/file/D67E2BA6086ED32238E0E56F45B3E9DD64907CA0D19F

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "0",
    "errorCode": "0",
    "id": "D67E2BA6086ED32238E0E56F45B3E9DD64907CA0D19F",
    "type": "file"
}

Example 3

The following example returns an error because the file ID is invalid.

GET .../publiclinks/file/D7A271E0FCA45152EB13971E45B3E9DD64907CA0D19F

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "count": "0",
    "errorCode": "-16",
    "errorKey": "!csUnableToRetrieveSharedLinkInfo!csSecurityValidationFailed!csFldDoesNotExist,D7A271E0FCA45152EB13971E45B3E9DD64907CA0D19F!csUnprivilegedSystemError",
    "errorMessage": "Failed to retrieve shared link information. Security validation failed. 'D7A271E0FCA45152EB13971E45B3E9DD64907CA0D19F' does not exist. The error was caused by an internally generated issue. The error has been logged.",
    "errorType": "file",
    "id": "D7A271E0FCA45152EB13971E45B3E9DD64907CA0D19F",
    "title": "Failed to retrieve shared link information. Security validation failed. 'D7A271E0FCA45152EB13971E45B3E9DD64907CA0D19F' 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"
}

Back to Top