REST API for Documents

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

multipart/form-data

Header Parameters

accessToken(optional): string

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.
appLinkID(optional): string

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.
dAccessCode(optional): 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(optional): string

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

jsonInputParameters: string

You can use this parameter to include the parentID parameter and the duplicateResolution parameter as a JSON payload with the request. This parameter must come before the primaryFile parameter.
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" }
metadataValues(optional): string

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" }
primaryFile: file

File to upload. This must come after the jsonInputParameters parameter.

Response

Supported Media Types

application/json
application/xml

201 Response

Created. The request was fulfilled and the new resource was created.

Headers

Location: string

The URI for the newly created resource is in the Location Header field.

Root Schema : FileUploadResponse

Type: object

The response body includes information about the file.

Show Source

errorCode(optional): number

An error code of zero (0) indicates no errors.
errorMessage(optional): string

An error code of zero (0) indicates no errors.

{
    "description":"The response body includes information about the file.",
    "type":"object",
    "allOf":[
        {
            "$ref":"#/definitions/FileDefinition"
        }
    ],
    "properties":{
        "errorCode":{
            "type":"number",
            "description":"An error code of zero (0) indicates no errors."
        },
        "errorMessage":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        }
    }
}

Match All

Show Source

object FileDefinition

File information

{
    "description":"The response body includes information about the file.",
    "type":"object",
    "allOf":[
        {
            "$ref":"#/definitions/FileDefinition"
        }
    ],
    "properties":{
        "errorCode":{
            "type":"number",
            "description":"An error code of zero (0) indicates no errors."
        },
        "errorMessage":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        }
    }
}

Nested Schema : FileDefinition

Type: object

File information

Show Source

createdBy(optional): object User

User information
createdTime(optional): string

File creation date.
id(optional): string

Globally unique identifier (GUID) for the file.
mimeType(optional): string

File format of the file.
modifiedBy(optional): object User

User information
modifiedTime(optional): string

File last modified date.
name(optional): string

File name.
ownedBy(optional): object User

User information
parentID(optional): string

Globally unique identifier (GUID) for the parent folder. If the parent folder is the user's home folder, the value for parentID is self.
reservationTime(optional): string

Time the file was reserved (excluded from response data if the file is not reserved).
reservedBy(optional): object User

User information
size(optional): string

Size of the file in bytes.
type(optional): string

Item type file.
version(optional): string

File version.

{
    "description":"File information",
    "properties":{
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the file."
        },
        "parentID":{
            "type":"string",
            "description":"<p>Globally unique identifier (GUID) for the parent folder. If the parent folder is the user&#39;s home folder, the value for <code>parentID</code> is <code>self</code>.</p>"
        },
        "name":{
            "type":"string",
            "description":"File name."
        },
        "mimeType":{
            "type":"string",
            "description":"File format of the file."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>file</code>."
        },
        "size":{
            "type":"string",
            "description":"Size of the file in bytes."
        },
        "version":{
            "type":"string",
            "description":"File version."
        },
        "createdTime":{
            "type":"string",
            "description":"File creation date."
        },
        "modifiedTime":{
            "type":"string",
            "description":"File last modified date."
        },
        "reservationTime":{
            "type":"string",
            "description":"Time the file was reserved (excluded from response data if the file is not reserved)."
        },
        "createdBy":{
            "$ref":"#/definitions/User"
        },
        "ownedBy":{
            "$ref":"#/definitions/User"
        },
        "modifiedBy":{
            "$ref":"#/definitions/User"
        },
        "reservedBy":{
            "$ref":"#/definitions/User"
        }
    }
}

Nested Schema : User

Type: object

User information

Show Source

displayName(optional): string

The display name for the user.
id(optional): string

Globally unique identifier (GUID) for the user.
loginName(optional): string

The login name for the user.
type(optional): string

Item type user.

{
    "description":"User information",
    "properties":{
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the user."
        },
        "displayName":{
            "type":"string",
            "description":"The display name for the user."
        },
        "loginName":{
            "type":"string",
            "description":"The login name for the user."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>user</code>."
        }
    }
}

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.

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