Newer Version Available

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

Insert or Update Blob Data

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, 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. The maximum file size for uploads is 2 GB for ContentVersion objects and 500 MB for all other eligible standard objects.

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

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

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

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.

1--boundary_string
2Content-Disposition: form-data; name="entity_document";
3Content-Type: application/json
4
5{  
6    "Description" : "Marketing brochure for Q1 2011",
7    "Keywords" : "marketing,sales,update",
8    "FolderId" : "005D0000001GiU7",
9    "Name" : "Marketing Brochure Q1",
10    "Type" : "pdf"
11}
12
13--boundary_string
14Content-Type: application/pdf
15Content-Disposition: form-data; name="Body"; filename="2011Q1MktgBrochure.pdf"
16
17Binary data goes here.
18
19--boundary_string--

Example response body for creating a new Document

On success, the ID of the new Document is returned.

1{
2    "id" : "015D0000000N3ZZIA0",
3    "errors" : [ ],
4    "success" : true
5}

Example error response

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

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

1curl https://yourInstance.salesforce.com/services/data/v23.0/Document/015D0000000N3ZZIA0 -H "Authorization: Bearer token" -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. 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.

1--boundary_string
2Content-Disposition: form-data; name="entity_content";
3Content-Type: application/json
4
5{  
6    "Name" : "Marketing Brochure Q1 - Sales",
7    "Keywords" : "sales, marketing, first quarter"
8}
9
10--boundary_string
11Content-Type: application/pdf
12Content-Disposition: form-data; name="Body"; filename="2011Q1MktgBrochure.pdf"
13
14Updated document binary data goes here.
15
16--boundary_string--

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

1curl https://yourInstance.salesforce.com/services/data/v23.0/sobjects/ContentVersion -H "Authorization: Bearer token" -H "Content-Type: multipart/form-data; boundary=\"boundary_string\"" --data-binary @NewContentVersion.json

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.

1--boundary_string
2Content-Disposition: form-data; name="entity_content";
3Content-Type: application/json
4
5{
6    "ContentDocumentId" : "069D00000000so2",
7    "ReasonForChange" : "Marketing materials updated",
8    "PathOnClient" : "Q1 Sales Brochure.pdf"
9}
10
11--boundary_string
12Content-Type: application/octet-stream
13Content-Disposition: form-data; name="VersionData"; filename="Q1 Sales Brochure.pdf"
14
15Binary data goes here.
16
17--boundary_string--

Example response body for inserting a ContentVersion

1{
2    "id" : "068D00000000pgOIAQ",
3    "errors" : [ ],
4    "success" : true
5}

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.

Force.com REST API Developer Guide

Insert or Update Blob Data

Inserting a New Document

Updating a Document

Inserting a ContentVersion

Multipart Message Considerations