Insert or Update Blob Data

Note

This REST feature is currently available through a pilot program. For information on enabling it for your organization, contact salesforce.com.

You can use REST resources to insert or update blob data in Salesforce standard objects. You can upload files of any type with a size of up to 500 MB, and you must use a multipart message that conforms to the MIME multipart content-type standard. For more information, see the WC3 Standards. You can insert or update files on any standard object that contains a blob field.

Note

You can insert or update blob data using a non-multipart message, but if you do, you are limited to 50 MB of text data or 37.5 MB of base64–encoded data.

The first part of the request message body contains non–binary field data such as the Description or Name. The second part of the message contains the binary data of the file that you're uploading.

The following sections provide JSON examples of how to insert or update blob data using a multipart content-type.

Inserting a New Document
Updating a Document
Inserting a ContentVersion
Multipart Message Considerations

Inserting a New Document

This section contains the syntax and code for creating a new Document. In addition to the binary data of the file itself, this code also specifies other field data such as the Description, Keywords, Name, and so on.

Tip

After you add a new Document, you can view the results of your changes on the Documents tab.

Example usage for creating a new Document

curl https://instance name.salesforce.com/services/data/v23.0/sobjects/Document/ -H "Content-Type: multipart/form-data; boundary=\"boundary_string\"" --data-binary @newdocument.json -H "Authorization: OAuth token" -H "X-PrettyPrint:1"

Example request body for creating a new Document

This code is the contents of the file newdocument.json.

--boundary_string
Content-Disposition: form-data; name="entity_document";
Content-Type: application/json

{  
    "Description" : "Marketing brochure for Q1 2011",
    "Keywords" : "marketing,sales,update",
    "FolderId" : "005D0000001GiU7",
    "Name" : "Marketing Brochure Q1",
    "Type" : "pdf"
}

--boundary_string
Content-Type: application/pdf
Content-Disposition: form-data; name="Body"; filename="2011Q1MktgBrochure.pdf"

Binary data goes here.

--boundary_string--

Example response body for creating a new Document

{
    "id" : "015D0000000N3ZZIA0",
    "errors" : [ ],
    "success" : true
}

Example error response

{
    "fields" : [ "FolderId" ],
    "message" : "Folder ID: id value of incorrect type: 005D0000001GiU7",
    "errorCode" : "MALFORMED_ID"
}

For more information about error codes, see Error Response.

Updating a Document

This section contains the syntax and code for updating an existing Document. In addition to the binary data of the file itself, this code also updates other field data such as the Name and Keywords.

Example usage for updating fields in a Document object

curl https://instance name.salesforce.com/services/data/v23.0/sobjects/Document/015D0000000N3ZZIA0  -H "Authorization: OAuth token" -H "X-PrettyPrint:1" -H "Content-Type: multipart/form-data; boundary=\"boundary_string\"" --data-binary @UpdateDocument.json -X PATCH

Example request body for updating fields in a Document object

This code is the contents of the file UpdateDocument.json.

--boundary_string
Content-Disposition: form-data; name="entity_content";
Content-Type: application/json

{  
    "Name" : "Marketing Brochure Q1 - Sales",
    "Keywords" : "sales, marketing, first quarter"
}

--boundary_string
Content-Type: application/pdf
Content-Disposition: form-data; name="Body"; filename="2011Q1MktgBrochure.pdf"

Updated document binary data goes here.

--boundary_string--

Example response body for updating fields in a Document object

none returned

Error responses

See Error Response.

Inserting a ContentVersion

This section contains the syntax and code for inserting a new ContentVersion. In addition to the binary data of the file itself, this code also updates other fields such as the ReasonForChange and PathOnClient. This message contains the ContentDocumentId because a ContentVersion is always associated with a ContentDocument.

Tip

The ContentVersion object doesn't support updates. Therefore, you cannot update a ContentVersion, you can only insert a new ContentVersion. You can see the results of your changes on the Content tab.

Example usage for inserting a ContentVersion

curl https://instance name.salesforce.com/services/data/v23.0/sobjects/ContentVersion-H "Content-Type: multipart/form-data; boundary=\"boundary_string\"" --data-binary @c:\CurlTest\NewContentVersion.json -H "Authorization: OAuth token" -H "X-PrettyPrint:1"

Example request body for inserting a ContentVersion

--boundary_string
Content-Disposition: form-data; name="entity_content";
Content-Type: application/json

{
    "ContentDocumentId" : "069D00000000so2",
    "ReasonForChange" : "Marketing materials updated",
    "PathOnClient" : "Q1 Sales Brochure.pdf"
}

--boundary_string
Content-Type: application/octet-stream
Content-Disposition: form-data; name="VersionData"; filename="Q1 Sales Brochure.pdf"

Binary data goes here.

--boundary_string--

Example response body for inserting a ContentVersion

{
    "id" : "068D00000000pgOIAQ",
    "errors" : [ ],
    "success" : true
}

Error responses for inserting a ContentVersion

See Error Response.

Multipart Message Considerations

Following are some considerations for the format of a multipart message when you insert or update blob data.

Boundary String

Separates the various parts of a multipart message.
Required in a multipart content-type.
Can be up to 70 characters.
Cannot be a string value that appears anywhere in any of the message parts.
The first boundary string must be prefixed by two hyphens (--).
The last boundary string must be postfixed by two hyphens (--).

Content-Disposition Header

Required in each message part.
Must be the value form-data and have a name attribute.
- In the non-binary part of the message, the name attribute can be any value.
- In the binary part of the message, the name attribute should contain the name of the object field that will contain the binary data. In the previous example of adding a new Document, the name of the binary field that contains the file is Body.
The binary part of the message must have a filename attribute which represents the name of the local file.

Content-Type Header

Required in each message part.
The content types supported by the non-binary message part are application/json and application/xml.
The Content-Type header for the binary part of the message can be any value.

New Line

There must be a new line between the message part header and the data of the part. As shown in the code examples, there must be a new line between the Content-Type and Content-Disposition headers and the JSON or XML. In the binary part, there must be a new line between the Content-Type and Content-Disposition headers and the binary data.