Get Information on Multiple Files
/documents/api/1.1/files/lists
Get file information for a list of files.
Request
- application/json
- application/xml
- idList
-
Type:
string
Required:true
A comma-separated list of globally unique identifiers (GUIDs) for files. There is a limit of 100 file IDs
- accessToken
-
Type:
string
Applink access token authorizing the current user to access the parent folder or this file. 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 the parent folder or this file. Any time the parameter
appLinkID
is used, a parameteraccessToken
must be provided as well. 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. It can be used as linkID or LinkID.
Response
- application/json
- application/xml
The response body contains information about the specific files.
object
- errorCode
-
Type:
number
An error code of zero (0) indicates no errors.
-
Type:
object
FileDefinitionWithConversationAdditional Properties Allowed:File information
- conversationID
-
Type:
string
Conversation ID associated with this file or a parent folder. - createdBy
-
Type:
object
UserAdditional Properties Allowed:User information - createdTime
-
Type:
string
File creation date. - id
-
Type:
string
Globally unique identifier (GUID) for the file. - isConversationInherited
-
Type:
boolean
Flag indicating whether the conversation ID is associated with the current file (false) or if the conversation ID is associated with a parent folder (true). - mimeType
-
Type:
string
File format of the file. - modifiedBy
-
Type:
object
UserAdditional Properties Allowed:User information - modifiedTime
-
Type:
string
File last modified date. - name
-
Type:
string
File 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
. - reservationTime
-
Type:
string
Time the file was reserved (excluded from response data if the file is not reserved). - reservedBy
-
Type:
object
UserAdditional Properties Allowed:User information - size
-
Type:
string
Size of the file in bytes. - type
-
Type:
string
Item typefile
. - version
-
Type:
string
File version.
- 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
{
"errorCode":"0",
"items":[
{
"type":"file",
"size":"129756",
"mimeType":"image/jpeg",
"version":"1",
"createdTime":"2017-06-09T15:23:34Z",
"createdBy":{
"displayName":"UserAA",
"id":"U5C4D5FCE14F2B44946FA74745B3E9DD6490",
"loginName":"UserAA",
"type":"user"
},
"id":"D9B1139A67E4F7F382AA55C145B3E9DD6490EDC3EE22",
"name":"exif-xmp.jpg",
"modifiedTime":"2017-06-09T15:23:34Z",
"modifiedBy":{
"displayName":"UserAA",
"id":"U5C4D5FCE14F2B44946FA74745B3E9DD6490",
"loginName":"UserAA",
"type":"user"
},
"ownedBy":{
"displayName":"UserAA",
"id":"U5C4D5FCE14F2B44946FA74745B3E9DD6490",
"loginName":"UserAA",
"type":"user"
},
"parentID":"F1B1C454FD92B47E9EB6883845B3E9DD6490EDC3EE22"
}
]
}
The idList
parameter is missing or has more than 100 file IDs.
The user does not have access to one or more of the file IDs.
One or more of the file IDs do not exist.
Examples
The following example returns information about 4 separate files.
GET ..files/lists?idList=D9B1139A67E4F7F382AA55C145B3E9DD6490EDC3EE22,DA0241950204386B4A51A43545B3E9DD6490EDC3EE22,DA6C23C749A3DFD38B6B165845B3E9DD6490EDC3EE22,D2FE9E3269F0EAFB280F599845B3E9DD6490EDC3EE22
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "errorCode": "0", "items": [ { "type": "file", "size": "129756", "mimeType": "image/jpeg", "version": "1", "createdTime": "2017-06-09T15:23:34Z", "createdBy": { "displayName": "UserAA", "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490", "loginName": "userAALoginName", "type": "user" }, "id": "D9B1139A67E4F7F382AA55C145B3E9DD6490EDC3EE22", "name": "exif-xmp.jpg", "modifiedTime": "2017-06-09T15:23:34Z", "modifiedBy": { "displayName": "UserAA", "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490", "loginName": "userAALoginName", "type": "user" }, "ownedBy": { "displayName": "UserAA", "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490", "loginName": "userAALoginName", "type": "user" }, "parentID": "F1B1C454FD92B47E9EB6883845B3E9DD6490EDC3EE22" }, { "type": "file", "size": "24205", "mimeType": "image/jpeg", "version": "1", "createdTime": "2017-06-09T15:22:13Z", "createdBy": { "displayName": "UserAA", "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490", "loginName": "userAALoginName", "type": "user" }, "id": "DA0241950204386B4A51A43545B3E9DD6490EDC3EE22", "name": "BlueSquare.jpg", "modifiedTime": "2017-06-09T15:22:13Z", "modifiedBy": { "displayName": "UserAA", "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490", "loginName": "userAALoginName", "type": "user" }, "ownedBy": { "displayName": "UserAA", "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490", "loginName": "userAALoginName", "type": "user" }, "parentID": "F7A9B089812185D3178AED0845B3E9DD6490EDC3EE22" }, { "type": "file", "size": "52", "mimeType": "text/plain", "version": "1", "createdTime": "2017-06-09T19:46:26Z", "createdBy": { "displayName": "UserAA", "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490", "loginName": "userAALoginName", "type": "user" }, "id": "DA6C23C749A3DFD38B6B165845B3E9DD6490EDC3EE22", "name": "d.txt", "modifiedTime": "2017-06-09T19:46:26Z", "modifiedBy": { "displayName": "UserAA", "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490", "loginName": "userAALoginName", "type": "user" }, "ownedBy": { "displayName": "UserAA", "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490", "loginName": "userAALoginName", "type": "user" }, "parentID": "self" }, { "type": "file", "size": "52", "mimeType": "text/plain", "version": "1", "createdTime": "2017-06-09T19:32:20Z", "createdBy": { "displayName": "UserBB", "id": "UF304F8B86A81760EAA3D94F45B3E9DD6490", "loginName": "userBBLoginName", "type": "user" }, "id": "D2FE9E3269F0EAFB280F599845B3E9DD6490EDC3EE22", "name": "g.txt", "modifiedTime": "2017-06-09T19:32:20Z", "modifiedBy": { "displayName": "UserBB", "id": "UF304F8B86A81760EAA3D94F45B3E9DD6490", "loginName": "userBBLoginName", "type": "user" }, "ownedBy": { "displayName": "UserBB", "id": "UF304F8B86A81760EAA3D94F45B3E9DD6490", "loginName": "userBBLoginName", "type": "user" }, "parentID": "F80D8BB2B2F8B549A9CEC22045B3E9DD6490EDC3EE22" } ] }
Example 2
The following example returns an error because one or more of the specified file IDs do not exist. When there are multiple file IDs, the first ID with an error is used in the error message.
GET ../files/lists?idList=D8B1139A67E4F7F382AA55C145B3E9DD6490EDC3EE22,DA0241950204386B4A51A43545B3E9DD6490EDC3EE22,DA6C23C749A3DFD38B6B165845B3E9DD6490EDC3EE22,D2FE9E3269F0EAFB280F599845B3E9DD6490EDC3EE22
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 404
JSON Response
{ "errorCode": "-16", "errorKey": "!csSecurityValidationFailed!csFldDoesNotExist,D8B1139A67E4F7F382AA55C145B3E9DD6490EDC3EE22!csUnprivilegedSystemError", "errorMessage": "Security validation failed. 'D8B1139A67E4F7F382AA55C145B3E9DD6490EDC3EE22' does not exist. The error was caused by an internally generated issue. The error has been logged.", "errorType": "file", "idList": "D8B1139A67E4F7F382AA55C145B3E9DD6490EDC3EE22,DA0241950204386B4A51A43545B3E9DD6490EDC3EE22,DA6C23C749A3DFD38B6B165845B3E9DD6490EDC3EE22,D2FE9E3269F0EAFB280F599845B3E9DD6490EDC3EE22", "title": "Security validation failed. 'D8B1139A67E4F7F382AA55C145B3E9DD6490EDC3EE22' 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 3
The following example returns an error because the idList
parameter includes a folder ID.
GET ../files/lists?idList=FD1100FD6787FAA2AEBEBAFE45B3E9DD6490EDC3EE22
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 404
JSON Response
{ "errorCode": "-16", "errorKey": "!csSecurityValidationFailed!csFldDoesNotExist,FD1100FD6787FAA2AEBEBAFE45B3E9DD6490EDC3EE22!csUnprivilegedSystemError", "errorMessage": "Security validation failed. 'FD1100FD6787FAA2AEBEBAFE45B3E9DD6490EDC3EE22' does not exist. The error was caused by an internally generated issue. The error has been logged.", "errorType": "file", "idList": "FD1100FD6787FAA2AEBEBAFE45B3E9DD6490EDC3EE22", "title": "Security validation failed. 'FD1100FD6787FAA2AEBEBAFE45B3E9DD6490EDC3EE22' 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 4
The following example returns an error because the required idList
parameter is missing from the request.
GET ../files/lists/
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 400
JSON Response
{ "errorCode": "-97", "errorKey": "!csRequiredFieldMissing,idList", "errorMessage": "Required field 'idList' is missing.", "title": "Required field 'idList' is missing.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 5
The following example returns an error because the idList
parameter is limited to 100 IDs.
GET ../files/lists?idList=D045499BB501A61CCCEE8F8845B3E9DD6490EDC3EE22,D644B8E0245A02B398748B3145B3E9DD6490EDC3EE22,DFBA6890D77D5D4748B70AF145B3E9DD6490EDC3EE22,D3CEF5A5BA835D9F68C338C945B3E9DD6490EDC3EE22,D5FCE2AFBC8649135EFF991045B3E9DD6490EDC3EE22,D961CB2756AFBD4EDEE9824B45B3E9DD6490EDC3EE22,D11B004C740D6AA23D415F2F45B3E9DD6490EDC3EE22,D51CB1D3136AE12331F0946145B3E9DD6490EDC3EE22,D8CECA5E959B79C06050CF4045B3E9DD6490EDC3EE22,DB8DF57B50E3CC6AE839FC5B45B3E9DD6490EDC3EE22,D78D7F7F2804C27314576A8045B3E9DD6490EDC3EE22,D78C1C8A0E81753C91637D9E45B3E9DD6490EDC3EE22,D938AE5E507BB4DDF1F3464445B3E9DD6490EDC3EE22,D18D37D70C541CADB8C02B8C45B3E9DD6490EDC3EE22,D7E0CA7B177B84E440292F5345B3E9DD6490EDC3EE22,DC393D36FDFA6D723CE1362445B3E9DD6490EDC3EE22,D4919A5E8498F9EF194BB67545B3E9DD6490EDC3EE22,D63F6931D9F035AE38EEEA7545B3E9DD6490EDC3EE22,D7FB2B347CB29A3EA2CA133F45B3E9DD6490EDC3EE22,DF50BF511C0531ABE8D3B81D45B3E9DD6490EDC3EE22,DAA8CA6BDA8AB9A7CEE23BF345B3E9DD6490EDC3EE22,D5B1618B48084AEE3E3AC65145B3E9DD6490EDC3EE22,DCEB1F0545414F7F3563711C45B3E9DD6490EDC3EE22,DFFA0E5F44A1536C765FBB8445B3E9DD6490EDC3EE22,D5CBA9AD4046439C9C900ADF45B3E9DD6490EDC3EE22,D730DF64DBD343FD3E3F577A45B3E9DD6490EDC3EE22,D6759B0A227D27BF26AAEB1845B3E9DD6490EDC3EE22,DAED69C1E8F2FBD26D3CAE9D45B3E9DD6490EDC3EE22,D121DC05D24E771149AC5C4145B3E9DD6490EDC3EE22,D25BB8A7085D7B7D1D76FED345B3E9DD6490EDC3EE22,DF095D1628A983F6D807FC8B45B3E9DD6490EDC3EE22,D1F4EAAD383B9C8E71BDA4E445B3E9DD6490EDC3EE22,DFE2E77DC330DC72E8F3146D45B3E9DD6490EDC3EE22,D2AF74632412E78D276BFCD745B3E9DD6490EDC3EE22,DD3EEACD8D9E32A981C45CCC45B3E9DD6490EDC3EE22,D73273873AFA498A1873ED8545B3E9DD6490EDC3EE22,DB7B1CEE039553CB8350D70C45B3E9DD6490EDC3EE22,D55018FC7EB04501CAFB797A45B3E9DD6490EDC3EE22,D287602012621C3C254A209945B3E9DD6490EDC3EE22,DF0798188190C999FBCECFE245B3E9DD6490EDC3EE22,DA12EBD156E2412477758AFB45B3E9DD6490EDC3EE22,D5B0AF58A980F1CFBC0FAB3C45B3E9DD6490EDC3EE22,DE73C88D987553BE0A09F5E345B3E9DD6490EDC3EE22,D043FF5F92324993428AE88845B3E9DD6490EDC3EE22,D6BA4CCFFB37F4FA62488DDF45B3E9DD6490EDC3EE22,DF96AF28ACDFE93AE842D32045B3E9DD6490EDC3EE22,DF75E3FFE45570DE5430F67145B3E9DD6490EDC3EE22,DCCF3D164AFA37062400A94745B3E9DD6490EDC3EE22,D29CC178D4376C31DF5E94DE45B3E9DD6490EDC3EE22,D6F743EB4CF4A67590B8338945B3E9DD6490EDC3EE22,D01EAAA75F6F4F0AC368829B45B3E9DD6490EDC3EE22,D16AA10B20A829B1EB5D897745B3E9DD6490EDC3EE22,DD4CCBB4F256677F3FB6199B45B3E9DD6490EDC3EE22,DEBD05A5D3425BB0B7450AC045B3E9DD6490EDC3EE22,DED396C80F6883AB6329F69345B3E9DD6490EDC3EE22,D4D56AED18612A3B73107C9745B3E9DD6490EDC3EE22,DD7111AEC772A8061500015545B3E9DD6490EDC3EE22,DB4B27FDADCE35E608D4B65845B3E9DD6490EDC3EE22,D6D41E7E0F581AFA290C258445B3E9DD6490EDC3EE22,D1E8642FEF84CC7E4494F0A245B3E9DD6490EDC3EE22,D702D5C735762A6924A7084345B3E9DD6490EDC3EE22,D521CF35D61EE9AE5FC3CD4245B3E9DD6490EDC3EE22,D56B9AA1B7DB32D9A8F8218545B3E9DD6490EDC3EE22,D4394E08B1918AE29D1443CC45B3E9DD6490EDC3EE22,DA4D009D61DD3AA43556791145B3E9DD6490EDC3EE22,D4EB2F763E305E62734DA34E45B3E9DD6490EDC3EE22,DD8C26BBAED0D0710CB3CD9945B3E9DD6490EDC3EE22,D12B406BD0B5A46533653DB745B3E9DD6490EDC3EE22,DA86C6B36B4C87976BBDD67445B3E9DD6490EDC3EE22,D83087A4995766E152D2614045B3E9DD6490EDC3EE22,D6DF800FCB7BB40D0B4E891645B3E9DD6490EDC3EE22,DEFDD863068F19E59451852445B3E9DD6490EDC3EE22,D29EB6FC637DBA7BD762608845B3E9DD6490EDC3EE22,D80CBC8B4572D35E7B494D9C45B3E9DD6490EDC3EE22,DA1EE11C6AABEF260C518EA245B3E9DD6490EDC3EE22,D7AB9279221F38C2BCB2860C45B3E9DD6490EDC3EE22,D9F13BFAFF2253E0C6BB090245B3E9DD6490EDC3EE22,D4E8FB5A201A14F45D07AA5345B3E9DD6490EDC3EE22,D08C5539DF2DB54A4C3953A345B3E9DD6490EDC3EE22,D4E97E8D8E05842861B5F2D445B3E9DD6490EDC3EE22,D436CF5F03D32DDDA067546945B3E9DD6490EDC3EE22,DBD0737E0F4BC418B5814F9C45B3E9DD6490EDC3EE22,D2623C452A3CD4466D653EAB45B3E9DD6490EDC3EE22,DEFB17AF31C0EE534C27E8F745B3E9DD6490EDC3EE22,DCF4BCDE20BF647331B52DF045B3E9DD6490EDC3EE22,DA6A643B106470F3E771A89145B3E9DD6490EDC3EE22,DC6E2A878CDD31203DFBA80045B3E9DD6490EDC3EE22,DD12C6F650610A7B2021FA8845B3E9DD6490EDC3EE22,D207515E17AC7ECF205300F845B3E9DD6490EDC3EE22,DAC79F9D13E547E8BB312DE645B3E9DD6490EDC3EE22,DDD6F3940A0C5BA7CB9DD5DA45B3E9DD6490EDC3EE22,DFA32AC582E177A8762699C445B3E9DD6490EDC3EE22,D614AE886E052095D3F8594845B3E9DD6490EDC3EE22,DA544BEE91CC28B7370A3E7545B3E9DD6490EDC3EE22,DB968C16B1B885027369D12B45B3E9DD6490EDC3EE22,DCDA692599944423A2CEE02345B3E9DD6490EDC3EE22,D011824C973D24B6FC19D67E45B3E9DD6490EDC3EE22,D05357D87967B2D162DDE82645B3E9DD6490EDC3EE22,D2C35B76C9DEBA81FA93EEF345B3E9DD6490EDC3EE22,DE3A224414960FE5C039FC7745B3E9DD6490EDC3EE22,DE8717420B007BA9E5F90B4645B3E9DD6490EDC3EE22
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 400
JSON Response
{ "errorCode": "-96", "errorKey": "!csFieldHasTooManyValues,idList", "errorMessage": "Field 'idList' has too many values.", "title": "Field 'idList' has too many values.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 6
The following example returns an error because the file is not owned by or shared with the user.
GET ..files/lists?idList=DEC0F4FDEECAC86063D069E645B3E9DD6490EDC3EE22
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 403
JSON Response
{ "errorCode": "-20", "errorKey": "!csCloudItemInsufficientPrivileges,UserAA,fFileGUID:DEC0F4FDEECAC86063D069E645B3E9DD6490EDC3EE22,FLD_INFO_REST_HELPER", "errorMessage": "User 'UserAA' has insufficient privilege to access fFileGUID:DEC0F4FDEECAC86063D069E645B3E9DD6490EDC3EE22 with service FLD_INFO_REST_HELPER.", "errorType": "file", "idList": "DEC0F4FDEECAC86063D069E645B3E9DD6490EDC3EE22", "title": "User 'UserAA' has insufficient privilege to access fFileGUID:DEC0F4FDEECAC86063D069E645B3E9DD6490EDC3EE22 with service FLD_INFO_REST_HELPER.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 7
The following example returns information about 2 separate files. The example uses an applink ID because these files are 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 ..files/lists?idList=D2DBEE6A36E32FBA40839BC6B5D17B95F47087F4E518,DBE5FBD6F740323BF3892425B5D17B95F47087F4E518
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
{ "errorCode": "0", "items": [ { "type": "file", "size": "595284", "mimeType": "image/jpeg", "version": "1", "createdTime": "2017-06-29T15:03:40Z", "createdBy": { "displayName": "Tenant2.UserA", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "loginName": "Tenant2.UserA", "type": "user" }, "id": "D2DBEE6A36E32FBA40839BC6B5D17B95F47087F4E518", "name": "Hydrangeas.jpg", "modifiedTime": "2017-06-29T15:03:40Z", "modifiedBy": { "displayName": "Tenant2.UserA", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "loginName": "Tenant2.UserA", "type": "user" }, "ownedBy": { "displayName": "Tenant2.UserA", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "loginName": "Tenant2.UserA", "type": "user" }, "parentID": "FDC22B65E850730CAA60AF83B5D17B95F47087F4E518" }, { "type": "file", "size": "45", "mimeType": "text/html", "version": "1", "createdTime": "2017-06-29T15:10:45Z", "createdBy": { "displayName": "Tenant2.UserA", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "loginName": "Tenant2.UserA", "type": "user" }, "id": "DBE5FBD6F740323BF3892425B5D17B95F47087F4E518", "name": "Sample HTML.htm", "modifiedTime": "2017-06-29T15:10:45Z", "modifiedBy": { "displayName": "Tenant2.UserA", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "loginName": "Tenant2.UserA", "type": "user" }, "ownedBy": { "displayName": "Tenant2.UserA", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "loginName": "Tenant2.UserA", "type": "user" }, "parentID": "FDC22B65E850730CAA60AF83B5D17B95F47087F4E518" } ] }