Get Folder
/documents/api/1.2/folders/{folderId}
Get folder information for the specified folder.
Request
- application/json
- application/xml
-
folderId: string
Globally unique identifier (GUID) for the folder. If the referenced folder is the user's home folder, the value for
folderId
isself
.
-
accessToken(optional): string
Applink access token authorizing the current user to access this folder. This parameter is mandatory if
appLinkID
is used. It can be used as accessToken or AccessToken. -
appLinkID(optional): string
Applink ID authorizing the current user to access this folder. Any time the parameter
appLinkID
is used, a parameteraccessToken
must be provided as well. It can be used as appLinkID or AppLinkID. -
dAccessCode(optional): string
Access code needed to use protected public links. It needs to be sent as part of a Cookie header in the following format:
dAccessCode-<linkID>=<passcodeValue>
-
linkID(optional): string
Public link ID of a public link authorizing the current user to access this folder. It can be used as linkID or LinkID.
Response
- application/json
- application/xml
200 Response
The response body contains information about the specific folder.
object
-
errorCode(optional):
string
An error code of zero (0) indicates no errors.
-
object
FolderDefinitionWithConversation
Folder metadata information.
object
-
childitemsCount(optional):
string
Number of items contained in the folder.
-
conversationID(optional):
string
Conversation ID associated with this folder or a parent folder.
-
createdBy(optional):
object User
User information
-
createdTime(optional):
string
Date the folder was created.
-
description(optional):
string
Folder description.
-
id(optional):
string
Globally unique identifier (GUID) for the folder.
-
isConversationInherited(optional):
boolean
Flag indicating whether the conversation ID is associated with the current folder (false) or if the conversation ID is associated with a parent folder (true).
-
modifiedBy(optional):
object User
User information
-
modifiedTime(optional):
string
Date the folder was last modified.
-
name(optional):
string
Folder name.
-
ownedBy(optional):
object User
User information
-
parentID(optional):
string
Globally unique identifier (GUID) for the parent folder. If the parent folder is the user's home folder, the value for
parentID
isself
. -
size(optional):
string
Size of the folder in bytes, including all of the files and folders contained in the folder.
-
type(optional):
string
Item type
folder
.
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
.
{
"childItemsCount":"2",
"createdBy":{
"displayName":"User AA",
"loginName":"userAALoginName",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"type":"user"
},
"createdTime":"2014-02-21T20:52:37Z",
"errorCode":"0",
"id":"FF4729683CD68C1AFB1AE87DT0000000000100000001",
"modifiedBy":{
"displayName":"User AA",
"loginName":"userAALoginName",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"type":"user"
},
"modifiedTime":"2014-02-21T20:52:37Z",
"name":"foldera",
"ownedBy":{
"displayName":"User AA",
"loginName":"userAALoginName",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"type":"user"
}
}
self
39
folder
403 Response
Forbidden if the user does not have read permission.
404 Response
Folder ID is not found.
Examples
The following example returns folder-definition information for the specified folder.
GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "childItemsCount": "2", "createdBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "createdTime": "2014-02-21T20:52:37Z", "errorCode": "0", "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "modifiedTime": "2014-02-21T20:52:37Z", "name": "foldera", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "parentID": "self", "size": "39", "type": "folder" }
Example 2
The following example returns folder-definition information for the specified folder. This folder has a conversation associated with it, so two new fields, conversationID
and isConversationInherited
, are returned as well.
GET .../folders/F3EA22EE4F524F2931AAA841T0000000000100000001
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "childItemsCount": "1", "conversationID": "39912", "createdBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "createdTime": "2016-05-13T20:40:24Z", "errorCode": "0", "id": "F3EA22EE4F524F2931AAA841T0000000000100000001", "isConversationInherited": "false", "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "modifiedTime": "2016-05-13T20:40:24Z", "name": "folderB", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "parentID": "self", "size": "0", "type": "folder" }
Example 3
The following example returns folder-definition information for the specified folder. The example uses a public link ID because this folder is under a folder structure not owned by or shared with the current user.
GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
Request Body
None.
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "childItemsCount": "4", "createdBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "createdTime": "2016-06-06T21:34:23Z", "description": "PublicLinkDemo", "errorCode": "0", "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "modifiedTime": "2016-06-06T21:34:23Z", "name": "PublicLinkDemo", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "size": "1189", "type": "folder" }
Example 4
The following example returns folder-definition information for the specified folder. The example uses a public link ID protected by an access code because this folder is under a folder structure not owned by or shared with the current user. An access code (test12345
) is submitted as part of a Cookie in the request header.
GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518 Cookie: dAccessCode-LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518=test12345
Request Body
None.
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "childItemsCount": "4", "createdBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "createdTime": "2016-06-06T21:34:23Z", "description": "PublicLinkDemo", "errorCode": "0", "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "modifiedTime": "2016-06-06T21:34:23Z", "name": "PublicLinkDemo", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "size": "1189", "type": "folder" }
Example 5
The following example requests folder-definition information for the specified folder. Because this folder is under a folder structure not owned by or shared with the current user, an access denied error message is returned.
GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 403
JSON Response
{ "errorCode": "-20", "errorKey": "!csCloudItemInsufficientPrivileges,User BB,fFolderGUID:FF4729683CD68C1AFB1AE87DT0000000000100000001,FLD_INFO", "errorMessage": "User 'User BB' has insufficient privilege to access fFolderGUID:FF4729683CD68C1AFB1AE87DT0000000000100000001 with service FLD_INFO.", "errorType": "folder", "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "title": "User 'User BB' has insufficient privilege to access fFolderGUID:FF4729683CD68C1AFB1AE87DT0000000000100000001 with service FLD_INFO.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 6
The following example requests folder-definition information for the specified folder. This folder is under a folder structure not owned by or shared with the current user, and only a public link protected by an access code is available. An error is returned because the access code was not submitted as part of the request.
GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
Request Body
None.
HTTP Status Code
HTTP_STATUS = 403
JSON Response
{ "errorCode": "-18", "errorKey": "!csAccessCodeRequiredForLinkAccess", "errorMessage": "The access code must be provided to access the link.", "errorType": "folder", "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "title": "The access code must be provided to access the link.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 7
The following example returns folder-definition information for the specified folder. The example uses an applink because this folder is under a folder structure not owned by or shared with the current user. The applink ID and access token are submitted in the request header.
GET .../folders/F4927423081AA3C261E1D45AB5D17B95F47087F4E518
Request Header
appLinkID: LF5Bxj4TPo_p4n4qWn0tbKTicR2cTUJKv7X_ng9E7ry93rRuDokPqS1d6-wKwhb_wtcGYFDsI_cNMxeKQ-HR-FXQhiVoGRTYM_MPZY8qpICfYU94mmnMjM_cvsRhKMzc0NJgvwEJfqqDwPsAVrhc8cmg== accessToken: 352FpiMmW66PeYI1Gh5b83I9CXRwZhLfYAu4TXdqpzD8uNKUBMZVVJ3ZvivUW8kQ
Request Body
None.
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "childItemsCount": "0", "createdBy": { "displayName": "User BB", "id": "U5083EA1954687218BA6C3D9B5D17B95F470", "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470", "type": "user" }, "createdTime": "2017-06-15T21:08:54Z", "description": "subFolderTestByUserB CONTRIBUTOR applink", "errorCode": "0", "id": "F4927423081AA3C261E1D45AB5D17B95F47087F4E518", "modifiedBy": { "displayName": "User BB", "id": "U5083EA1954687218BA6C3D9B5D17B95F470", "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470", "type": "user" }, "modifiedTime": "2017-06-15T21:08:54Z", "name": "subFolderTestByUserB", "ownedBy": { "displayName": "User AA", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "loginName": "userAALoginName", "type": "user" }, "parentID": "FAD7A87F0613A0CBDD4DA521B5D17B95F47087F4E518", "size": "0", "type": "folder" }