REST API Developer Guide

Introducing Lightning Platform REST API
Quick Start
Examples
Getting Information About My Organization
Working with Object Metadata
Working with Records
Working with Searches and Queries
Insert or Update Blob Data
Working with Recently Viewed Information
Managing User Passwords
Working with Approval Processes and Process Rules
Using Event Monitoring
Using Composite Resources
Reference
PDF

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, SObject Rows, or SObject Collections 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.

Using the SObject Basic Information or SObject Rows APIs, the maximum file size for uploads is 2 GB for ContentVersion objects and 500 MB for all other eligible standard objects. Using the SObject Collections API, the maximum total size of all files in a single request is 500 MB.

You can insert or update blob data using a non-multipart message, but 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 syntax and code creates 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, and Name.

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. The binary data for the PDF content has been omitted for brevity and replaced with “Binary data goes here.” An actual request contains 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 syntax and code updates 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. The binary data for the PDF content has been omitted for brevity and replaced with “Updated document binary goes here.” An actual request contains 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 syntax and code inserts 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. The binary data for the PDF content has been omitted for brevity and replaced with “Binary data goes here.” An actual request contains 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.

Using SObject Collections to Insert a Collection of Blob Records

This syntax and code inserts a collection of new Documents. In addition to the binary data of the files themselves, this code also specifies other field data, such as the Description and Name for each record in the collection.

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

Tip

Attributes
If you’re using sObject Collections with blob data, you must specify certain attribute values in addition to type in the request body’s attributes map.
Parameter Description
binaryPartName Required for blob data. A unique identifier for the binary part.
binaryPartNameAlias Required for blob data. The name of the field in which the binary data is inserted or updated.
Example for creating new Documents
1curl https://yourInstance.salesforce.com/services/data/v42.0/composite/sobjects/ -H "Authorization: Bearer token" -H "Content-Type: multipart/form-data; boundary=\"boundary_string\"" --data-binary @newdocuments.json
Example request body for creating new Documents
This code is the contents of newdocuments.json. The binary data for the PDF content has been omitted for brevity and replaced with “Binary data goes here.” An actual request contains the full binary content.
1--boundary_string
2Content-Disposition: form-data; name="collection"
3Content-Type: application/json
4
5{
6    "allOrNone" : false,
7    "records" :
8    [
9        {
10            "attributes" :
11            {
12                "type" : "Document",
13                "binaryPartName": "binaryPart1",
14                "binaryPartNameAlias": "Body"
15            },
16            "Description" : "Marketing Brochure",
17            "FolderId" : "005xx000001Svs4AAC",
18            "Name" : "Brochure",
19            "Type" : "pdf"
20        },
21        {
22            "attributes" :
23            {
24                "type" : "Document",
25                "binaryPartName": "binaryPart2",
26                "binaryPartNameAlias": "Body"
27            },
28            "Description" : "Pricing Overview",
29            "FolderId" : "005xx000001Svs4AAC",
30            "Name" : "Pricing",
31            "Type" : "pdf"
32        }
33    ]
34}
35
36--boundary_string
37Content-Disposition: form-data; name="binaryPart1"; filename="Brochure.pdf"
38Content-Type: application/pdf
39
40Binary data goes here.
41
42--boundary_string
43Content-Disposition: form-data; name="binaryPart2"; filename="Pricing.pdf"
44Content-Type: application/pdf
45
46Binary data goes here.
47
48--boundary_string--
Example response body for creating new Documents
On success, the IDs of the new Documents are returned.
1[
2    {
3        "id": "015xx00000013QjAAI",
4        "errors": [],
5        "success": true
6    },
7    {
8        "id": "015xx00000013QkAAI",
9        "errors": [],
10        "success": true
11    }
12]

For more information, see SObject Collections.

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.
    • For single documents, in the binary part of the message, use the name attribute to contain the name of the object field that contains the binary data. In the previous example of adding a new Document, the name of the binary field that contains the file is Body.
    • For documents inserted or updated using sObject Collections, use the name attribute to contain a unique identifier for the part. This identifier is referenced by the non-binary part of the message.
  • The binary part of the message must have a filename attribute that 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
A new line must be between the message part header and the data of the part. As shown in the code examples, a new line must be between the Content-Type and Content-Disposition headers and the JSON or XML. In the binary part, a new line must be between the Content-Type and Content-Disposition headers and the binary data.