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:
stringRequired:trueA comma-separated list of globally unique identifiers (GUIDs) for files. There is a limit of 100 file IDs
- accessToken
-
Type:
stringApplink access token authorizing the current user to access the parent folder or this file. This parameter is mandatory if
appLinkIDis used. It can be used as accessToken or AccessToken. - appLinkID
-
Type:
stringApplink ID authorizing the current user to access the parent folder or this file. Any time the parameter
appLinkIDis used, a parameteraccessTokenmust be provided as well. It can be used as appLinkID or AppLinkID. - dAccessCode
-
Type:
stringAccess 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:
stringPublic 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:
numberAn error code of zero (0) indicates no errors.
-
Type:
objectFileDefinitionWithConversationAdditional Properties Allowed:File information
- conversationID
-
Type:
stringConversation ID associated with this file or a parent folder. - createdBy
-
Type:
objectUserAdditional Properties Allowed:User information - createdTime
-
Type:
stringFile creation date. - id
-
Type:
stringGlobally unique identifier (GUID) for the file. - isConversationInherited
-
Type:
booleanFlag 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:
stringFile format of the file. - modifiedBy
-
Type:
objectUserAdditional Properties Allowed:User information - modifiedTime
-
Type:
stringFile last modified date. - name
-
Type:
stringFile name. - ownedBy
-
Type:
objectUserAdditional Properties Allowed:User information - parentID
-
Type:
stringGlobally unique identifier (GUID) for the parent folder. If the parent folder is the user's home folder, the value for
parentIDisself. - reservationTime
-
Type:
stringTime the file was reserved (excluded from response data if the file is not reserved). - reservedBy
-
Type:
objectUserAdditional Properties Allowed:User information - size
-
Type:
stringSize of the file in bytes. - type
-
Type:
stringItem typefile. - version
-
Type:
stringFile version.
- displayName
-
Type:
stringThe display name for the user. - id
-
Type:
stringGlobally unique identifier (GUID) for the user. - type
-
Type:
stringItem 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"
}
]
}