Force.com REST API Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Insert or Update Blob Data

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

Note

You can use SObject Basic Information and SObject Rows 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.

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.

Note

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

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.

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

Tip

Example for creating a new Document
Example request body for creating a new Document
This code is the contents of newdocument.json. Note that the binary data for the PDF content has been omitted for brevity and replaced with “Binary data goes here.” An actual request will contain the full binary content.
Example response body for creating a new Document
On success, the ID of the new Document is returned.
Example 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
Example request body for updating fields in a Document object

This code is the contents of the file UpdateDocument.json. Note that the binary data for the PDF content has been omitted for brevity and replaced with “Updated document binary goes here.” An actual request will contain the full binary content.

Example response body for updating fields in a Document object
none returned
Error responses
See Status Codes and Error Responses.

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.

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.

Tip

Example usage for inserting a ContentVersion
Example request body for inserting a ContentVersion

This code is the contents of the file NewContentVersion.json. Note that the binary data for the PDF content has been omitted for brevity and replaced with “Binary data goes here.” An actual request would will the full binary content.

Example response body for inserting a ContentVersion
Error responses for inserting a ContentVersion
See Status Codes and Error Responses.

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.