Get Information on Multiple Files

get

/documents/api/1.1/files/lists

Get file information for a list of files.

Request

Supported Media Types
  • application/json
  • application/xml
Query Parameters
idList
Type: string
Required: true

A comma-separated list of globally unique identifiers (GUIDs) for files. There is a limit of 100 file IDs

Header Parameters
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 parameter accessToken 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

Supported Media Types
  • application/json
  • application/xml
200 Response

The response body contains information about the specific files.

Body
The response body includes information about the file.
Root Schema : FileResponseWithConversation
Type: object
The response body includes information about the file.
Nested Schema : FileDefinitionWithConversation
File information
Nested Schema : User
User information
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"
        }
    ]
}
400 Response

The idList parameter is missing or has more than 100 file IDs.

403 Response

The user does not have access to one or more of the file IDs.

404 Response

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"
        }
    ]
}