Upload File

post

/documents/api/1.2/files/data

Upload a new file using a multipart request to specify destination and file information.

Note:

File names are not case-sensitive; that is, File_Name and file_name are considered identical. Two files cannot have the same name in a given folder.

By default, if a file with the same name exists in the target destination, the uploaded file replaces the existing file as a new revision.

The request is a multipart HTTP request where one part is a JSON object (jsonInputParameters) with the parentID and the other part is the content of the file itself (primaryFile). It is also possible to set metadata values using another JSON object (metadataValues).

Request

Supported Media Types
Header Parameters
  • Applink access token authorizing the current user to access the parent folder. This parameter is mandatory if appLinkID is used. It can be used as accessToken or AccessToken.

  • Applink ID authorizing the current user to access the parent folder. Any time the parameter appLinkID is used, a parameter accessToken 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.

  • 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>

  • Public link ID of a public link authorizing the current user to access this file. To work, this public link must have the contributor role granted. It can be used as linkID or LinkID.

Form Parameters
  • You can use this parameter to include the parentID parameter and the duplicateResolution parameter as a JSON payload with the request.

    Set parentID to the globally unique identifier (GUID) of the folder to upload the file to.

    The parentID parameter must be sent as a part of this JSON payload. This parameter is required.

    For example:

    {

    "parentID ": "FB4CD874EF94CD2CC1B60B72T"

    }

    Also, to resolve any conflict with duplicate file names, you can set duplicateResolution to TimeStampSuffix.

    The duplicateResolution parameter can be sent as a part of this JSON payload. This parameter is optional.

    For example:

    {

    "parentID ": "FB4CD874EF94CD2CC1B60B72T",

    "duplicateResolution ": "TimeStampSuffix"

    }

  • You can use this parameter to set metadata values to a collection already assigned to any parent folder. The rules are the same as those applied to the set metadata values REST API. Use Content-Type: application/json to describe this information as a JSON object.

    For example:

    {

    "collection ": "CollectionA",

    "fieldA ": "valueA",

    "fieldB ": "valueB",

    "fieldC ": "valueC"

    }
  • File to upload.
Back to Top

Response

Supported Media Types

201 Response

Created. The request was fulfilled and the new resource was created.
Headers
  • The URI for the newly created resource is in the Location Header field.
Body ()
Root Schema : FileUploadResponse
Type: object
The response body includes information about the file.
Show Source
Match All
Show Source
Nested Schema : FileDefinition
Type: object
File information
Show Source
Nested Schema : User
Type: object
User information
Show Source
Example Response (application/json)
{
    "id":"DB1C5AF480FFE61C588027A8T0000000000100000001",
    "parentID":"FF4729683CD68C1AFB1AE87DT0000000000100000001",
    "name":"example.txt",
    "type":"file",
    "size":"13",
    "version":"1",
    "createdTime":"2014-02-21T21:32:37Z",
    "modifiedTime":"2014-02-21T21:32:37Z",
    "createdBy":{
        "displayName":"User AA",
        "id":"U0EAA20910FAF3052ACB79E4T00000000001",
        "loginName":"userAALoginName",
        "type":"user"
    },
    "ownedBy":{
        "displayName":"User AA",
        "id":"U0EAA20910FAF3052ACB79E4T00000000001",
        "loginName":"userAALoginName",
        "type":"user"
    },
    "modifiedBy":{
        "displayName":"User AA",
        "id":"U0EAA20910FAF3052ACB79E4T00000000001",
        "loginName":"userAALoginName",
        "type":"user"
    },
    "errorCode":"0",
    "errorMessage":"Successfully checked in content item 'ADC412030000000000000000000002'."
}

400 Response

Request parameters are not formatted correctly.

403 Response

Forbidden if the user does not have write permission.

404 Response

Folder ID is not found.
Back to Top

Examples

The following example uploads a new file using a multipart request.

POST .../files/data

Request Header

The request is a multipart request with a specified boundary delimiter of the following general form:

Content-Type: multipart/form-data; boundary=---1234567890

Request Body

-----1234567890
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
"parentID":"FB4CD874EF94CD2CC1B60B72T0000000000100000001"
}
-----1234567890
Content-Disposition: form-data; name="primaryFile"; filename="example.txt"
Content-Type: text/plain
 
<File Content>
-----1234567890--

An example of an alternative request body follows.

-----1234567890
Content-Disposition: form-data; name="jsonInputParameters"

{
"parentID":"FB4CD874EF94CD2CC1B60B72T0000000000100000001"
}
-----1234567890
Content-Disposition: form-data; name="primaryFile"; filename="example.txt"
Content-Type: text/plain

<File Content>
-----1234567890--

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "createdTime": "2014-02-21T21:11:24Z",
    "errorCode": "0",
    "errorMessage": "Successfully checked in content item 'ADC412030000000000000000000002'.",
    "id": "D34A657B8723A96097F80926T0000000000100000001",
    "modifiedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "modifiedTime": "2014-02-21T21:11:24Z",
    "name": "example.txt",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "parentID": "FB4CD874EF94CD2CC1B60B72T0000000000100000001",
    "size": "13",
    "type": "file",
    "version": "1"
}

Example 2

The following example uploads a new file using a multipart request. The example uses a public link ID because this file is under a folder structure not owned by or shared with the current user.

POST .../files/data

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
"parentID":"F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518"
}
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="idcTestNewFileREST.txt"
Content-Type: text/plain

This is idcTestNewFileREST.txt v1
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 201

JSON Response

{
    "createdBy": {
        "displayName": "User BB",
        "loginName": "userBBLoginName",
        "id": "U6A0B35B0548F250914D18FDB5D17B95F470",
        "type": "user"
    },
    "createdTime": "2016-06-30T20:09:54Z",
    "errorCode": "0",
    "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000000801",
    "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000000801'.",
    "id": "D34BA589F6ACC07B6EA371C7B5D17B95F47087F4E518",
    "mimeType": "text/plain",
    "modifiedBy": {
        "displayName": "User BB",
        "loginName": "userBBLoginName",
        "id": "U6A0B35B0548F250914D18FDB5D17B95F470",
        "type": "user"
    },
    "modifiedTime": "2016-06-30T20:09:54Z",
    "name": "idcTestNewFileREST.txt",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "parentID": "F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518",
    "size": "33",
    "type": "file",
    "version": "1"
}

Example 3

The following example uploads a new file using a multipart request. The example uses a public link ID protected by an access code because this file 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 .../files/data

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
Cookie: dAccessCode-LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518=test12345

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
"parentID":"F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518"
}
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="idcTestNewFileREST.txt"
Content-Type: text/plain

This is idcTestNewFileREST.txt v1
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 201

JSON Response

{
    "createdBy": {
        "displayName": "User BB",
        "loginName": "userBBLoginName",
        "id": "U6A0B35B0548F250914D18FDB5D17B95F470",
        "type": "user"
    },
    "createdTime": "2016-06-30T20:09:54Z",
    "errorCode": "0",
    "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000000801",
    "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000000801'.",
    "id": "D34BA589F6ACC07B6EA371C7B5D17B95F47087F4E518",
    "mimeType": "text/plain",
    "modifiedBy": {
        "displayName": "User BB",
        "loginName": "userBBLoginName",
        "id": "U6A0B35B0548F250914D18FDB5D17B95F470",
        "type": "user"
    },
    "modifiedTime": "2016-06-30T20:09:54Z",
    "name": "idcTestNewFileREST.txt",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "parentID": "F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518",
    "size": "33",
    "type": "file",
    "version": "1"
}

Example 4

The following example requests an upload of a new file using a multipart request. Because this file is under a folder structure not owned by or shared with the current user, an access denied error message is returned.

POST .../files/data

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
"parentID":"F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518"
}
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="idcTestNewFileREST.txt"
Content-Type: text/plain

This is idcTestNewFileREST.txt v1
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 403

JSON Response

{
    "errorCode": "-20",
    "errorKey": "!csUnableToCheckIn,idcTestNewFileREST.txt!csCloudItemInsufficientPrivileges,User BB,fFolderGUID:F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518,CHECKIN_UNIVERSAL",
    "errorMessage": "Content item 'idcTestNewFileREST.txt' was not successfully checked in. User 'User BB' has insufficient privilege to access fFolderGUID:F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518 with service CHECKIN_UNIVERSAL.",
    "parentID": "F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518",
    "title": "Content item 'idcTestNewFileREST.txt' was not successfully checked in. User 'User BB' has insufficient privilege to access fFolderGUID:F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518 with service CHECKIN_UNIVERSAL.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 5

The following example requests an upload of a new file using a multipart request. This file 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.

POST .../files/data

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
"parentID":"F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518"
}
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="idcTestNewFileREST.txt"
Content-Type: text/plain

This is idcTestNewFileREST.txt v1
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 403

JSON Response

{
    "errorCode": "-18",
    "errorKey": "!csUnableToCheckIn,idcTestNewFileREST.txt!csAccessCodeRequiredForLinkAccess",
    "errorMessage": "Content item 'idcTestNewFileREST.txt' was not successfully checked in. The access code must be provided to access the link.",
    "parentID": "F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518",
    "title": "Content item 'idcTestNewFileREST.txt' was not successfully checked in. 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 uploads a new file using a multipart request. This example also sets metadata values for global collection CollectionA.

POST .../files/data

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="jsonInputParameters"

{
    "parentID":"F79B040D5393DAC0F3511BBAB5D17B95F47087F4E518"
}
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="fileWithMetadata.txt"
Content-Type: text/plain

This is a file containing metadata values.
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="metadataValues"
Content-Type: application/json

{
    "collection": "CollectionA",
    "fieldA": "valueA",
    "fieldB": "valueB",
    "fieldC": "valueC"
}
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 201

JSON Response

{
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "createdTime": "2016-07-13T19:47:23Z",
    "errorCode": "0",
    "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000001200",
    "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000001200'.",
    "id": "D4100E975A8096829C9CCB06B5D17B95F47087F4E518",
    "metadata": {
        "CollectionA": {
            "fieldA": "valueA",
            "fieldB": "valueB",
            "fieldC": "valueC"
        }
    },
    "mimeType": "text/plain",
    "modifiedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "modifiedTime": "2016-07-13T19:47:23Z",
    "name": "fileWithMetadata.txt",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "parentID": "F79B040D5393DAC0F3511BBAB5D17B95F47087F4E518",
    "size": "42",
    "type": "file",
    "version": "1"
}

Example 7

The following example uploads a new file using a multipart request. The example uses an applink because this file 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 .../files/data

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
appLinkID: LF5Bxj4TPo_p4n4qWn0tbKTicR2cTUJKv7X_ng9E7ry93rRuDokPqS1d6-wKwhb_wtcGYFDsI_cNMxeKQ-HR-FXQhiVoGRTYM_MPZY8qpICfYU94mmnMjM_cvsRhKMzc0NJgvwEJfqqDwPsAVrhc8cmg==
accessToken: 352FpiMmW66PeYI1Gh5b83I9CXRwZhLfYAu4TXdqpzD8uNKUBMZVVJ3ZvivUW8kQ

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
    "parentID":"FDC22B65E850730CAA60AF83B5D17B95F47087F4E518"
}
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="fileViaApplink.txt"
Content-Type: text/plain

This is fileViaApplink.txt v1
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 201

JSON Response

{
    "createdBy": {
        "displayName": "User BB",
        "id": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "type": "user"
    },
    "createdTime": "2017-06-26T15:29:00Z",
    "errorCode": "0",
    "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000007006",
    "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000007006'.",
    "id": "DED694950C14AFF280419F9AB5D17B95F47087F4E518",
    "mimeType": "text/plain",
    "modifiedBy": {
        "displayName": "User BB",
        "id": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "type": "user"
    },
    "modifiedTime": "2017-06-26T15:29:00Z",
    "name": "fileViaApplink.txt",
    "ownedBy": {
        "displayName": "User AA",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "loginName": "userAALoginName",
        "type": "user"
    },
    "parentID": "FDC22B65E850730CAA60AF83B5D17B95F47087F4E518",
    "size": "29",
    "type": "file",
    "version": "1"
}
Back to Top