Create Folder
/documents/api/1.1/folders/{folderId}
Create a new subfolder in the specified destination folder.
Note:
Two folders cannot have the same name in a given folder. Folder names are not case-sensitive; that is, Folder_Name
and folder_name
are considered identical. If a folder with the same name exists in the target destination, the name of the new folder is given a numeric increment. For example, if the folder my_folder
already exists, the new folder is named my_folder(2)
.
Request
- application/json
- application/xml
- folderId
-
Type:
string
Required:true
Globally unique identifier (GUID) for the folder. If the referenced folder is the user's home folder, the value for
folderId
isself
.
- accessToken
-
Type:
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
-
Type:
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. To work, this applink must have at least the contributor role granted. It can be used as appLinkID or AppLinkID. - dAccessCode
-
Type:
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
-
Type:
string
Public link ID of a public link authorizing the current user to access this folder. To work, this public link must have the contributor role granted. It can be used as linkID or LinkID.
- description
-
Type:
string
(Optional) Specify a description for the newly created folder. - name
-
Type:
string
Required:true
(Required) Specify the name of the newly created folder.
Example application/json
{
"name":"restFolder",
"description":"rest folder"
}
Response
- application/json
- application/xml
The response body contains information about the newly created folder.
object
- errorCode
-
Type:
string
An error code of zero (0) indicates no errors.
-
Type:
object
FolderDefinitionAdditional Properties Allowed:Folder metadata information.
- childitemsCount
-
Type:
string
Number of items contained in the folder. - createdBy
-
Type:
object
UserAdditional Properties Allowed:User information - createdTime
-
Type:
string
Date the folder was created. - description
-
Type:
string
Folder description. - id
-
Type:
string
Globally unique identifier (GUID) for the folder. - modifiedBy
-
Type:
object
UserAdditional Properties Allowed:User information - modifiedTime
-
Type:
string
Date the folder was last modified. - name
-
Type:
string
Folder name. - ownedBy
-
Type:
object
UserAdditional Properties Allowed:User information - parentID
-
Type:
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
-
Type:
string
Size of the folder in bytes, including all of the files and folders contained in the folder. - type
-
Type:
string
Item typefolder
.
- 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
{
"id":"FB4CD874EF94CD2CC1B60B72T0000000000100000001",
"parentID":"FF4729683CD68C1AFB1AE87DT0000000000100000001",
"name":"restFolder",
"description":"rest folder",
"type":"folder",
"size":"0",
"childItemsCount":"0",
"createdTime":"2014-02-21T20:56:07Z",
"modifiedTime":"2014-02-21T20:59:57Z",
"createdBy":{
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"displayName":"User AA",
"type":"user"
},
"ownedBy":{
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"displayName":"User AA",
"type":"user"
},
"modifiedBy":{
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"displayName":"User AA",
"type":"user"
},
"errorCode":"0"
}
Request parameters are not formatted correctly.
Forbidden if the user does not have write permission.
Folder ID is not found.
Examples
The following example creates a new folder.
POST .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
None.
Request Body
{ "name": "restFolder", "description": "rest folder" }
HTTP Status Code
HTTP_STATUS = 201
JSON Response
{ "childItemsCount": "0", "createdBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "createdTime": "2014-02-21T20:54:50Z", "description": "rest folder", "errorCode": "0", "id": "FB4CD874EF94CD2CC1B60B72T0000000000100000001", "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "modifiedTime": "2014-02-21T20:54:50Z", "name": "restFolder", "ownedBy": "{ "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "parentID": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "type": "folder" }
Example 2
The following example creates a new 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.
POST .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
Request Body
{ "name": "UserBBFolder", "description": "User BB folder created via public link" }
HTTP Status Code
HTTP_STATUS = 201
JSON Response
{ "childItemsCount": "0", "createdBy": { "displayName": "User BB", "loginName": "userBBLoginName", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "type": "user" }, "createdTime": "2016-06-30T23:34:21Z", "description": "User BB folder created via public link", "errorCode": "0", "id": "F81175D40FF57F19884AED0CB5D17B95F47087F4E518", "modifiedBy": { "displayName": "User BB", "loginName": "userBBLoginName", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "type": "user" }, "modifiedTime": "2016-06-30T23:34:21Z", "name": "UserBBFolder", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "parentID": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "type": "folder" }
Example 3
The following example creates a new 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
POST .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518 Cookie: dAccessCode-LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518=test12345
Request Body
{ "name": "UserBBFolder", "description": "User BB folder created via public link" }
HTTP Status Code
HTTP_STATUS = 201
JSON Response
{ "childItemsCount": "0", "createdBy": { "displayName": "User BB", "loginName": "userBBLoginName", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "type": "user" }, "createdTime": "2016-06-30T23:34:21Z", "description": "User BB folder created via public link", "errorCode": "0", "id": "F81175D40FF57F19884AED0CB5D17B95F47087F4E518", "modifiedBy": { "displayName": "User BB", "loginName": "userBBLoginName", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "type": "user" }, "modifiedTime": "2016-06-30T23:34:21Z", "name": "UserBBFolder", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "parentID": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "type": "folder" }
Example 4
The following example requests creation of a new folder. Because this folder would be under a folder structure not owned by or shared with the current user, an access denied error message is returned.
POST .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
None.
Request Body
{ "name": "UserBBFolder", "description": "User BB folder created via public link" }
HTTP Status Code
HTTP_STATUS = 403
JSON Response
{ "description": "User BB folder created via public link", "errorCode": "-20", "errorKey": "!csFldUnableToCreateFolder!csCloudItemInsufficientPrivileges,User BB,fFolderGUID:FF4729683CD68C1AFB1AE87DT0000000000100000001,FLD_CREATE_FOLDER", "errorMessage": "Unable to create folder. User 'User BB' has insufficient privilege to access fFolderGUID:FF4729683CD68C1AFB1AE87DT0000000000100000001 with service FLD_CREATE_FOLDER.", "errorType": "folder", "name": "UserBBFolder", "parentID": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "title": "Unable to create folder. User 'User BB' has insufficient privilege to access fFolderGUID:FF4729683CD68C1AFB1AE87DT0000000000100000001 with service FLD_CREATE_FOLDER.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 5
The following example requests creation of a new folder. This folder would be 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.
POST .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001
Request Header
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
Request Body
{ "name": "UserBBFolder", "description": "User BB folder created via public link" }
HTTP Status Code
HTTP_STATUS = 403
JSON Response
{ "description": "User BB folder created via public link", "errorCode": "-18", "errorKey": "!csFldUnableToCreateFolder!csAccessCodeRequiredForLinkAccess", "errorMessage": "Unable to create folder. The access code must be provided to access the link.", "errorType": "folder", "name": "UserBBFolder", "parentID": "FF4729683CD68C1AFB1AE87DT0000000000100000001", "title": "Unable to create folder. The access code must be provided to access the link.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 6
The following example creates a new 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.
POST .../folders/F9681146B0BAAB329B58D6CFB5D17B95F47087F4E518
Request Header
appLinkID: LF5Bxj4TPo_p4n4qWn0tbKTicR2cTUJKv7X_ng9E7ry93rRuDokPqS1d6-wKwhb_wtcGYFDsI_cNMxeKQ-HR-FXQhiVoGRTYM_MPZY8qpICfYU94mmnMjM_cvsRhKMzc0NJgvwEJfqqDwPsAVrhc8cmg== accessToken: 352FpiMmW66PeYI1Gh5b83I9CXRwZhLfYAu4TXdqpzD8uNKUBMZVVJ3ZvivUW8kQ
Request Body
{ "name": "subFolderTestByUserB", "description": "subFolderTestByUserB CONTRIBUTOR applink" }HTTP Status Code
HTTP_STATUS = 201
JSON Response
{ "childItemsCount": "0", "createdBy": { "displayName": "User BB", "id": "U5083EA1954687218BA6C3D9B5D17B95F470", "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470", "type": "user" }, "createdTime": "2017-06-21T18:53:43Z", "description": "subFolderTestByUserB CONTRIBUTOR applink", "errorCode": "0", "id": "FAA7449732E312E8174731B3B5D17B95F47087F4E518", "modifiedBy": { "displayName": "User BB", "id": "U5083EA1954687218BA6C3D9B5D17B95F470", "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470", "type": "user" }, "modifiedTime": "2017-06-21T18:53:43Z", "name": "subFolderTestByUserB", "ownedBy": { "displayName": "User AA", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "loginName": "userAALoginName", "type": "user" }, "parentID": "F9681146B0BAAB329B58D6CFB5D17B95F47087F4E518", "type": "folder" }