Insert or Update Blob Data

Inserting a Document with Blob Data

This example request and request body creates a Document record that contains the binary data of a PDF file. In addition to the binary data of the file itself, the request body also specifies other field data, including the FolderId, which is required for the Document object.

If you don’t have a Folder record for the new Document record in Salesforce, you must create one using the sObject Basic Information resource before you can follow this example. Make sure the Type field of the Folder record is Document.

Example request for creating a Document

curl https://MyDomainName.my.salesforce.com/services/data/v64.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 Document

This request body represents 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.

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

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

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

Example error response

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

Updating a Document with Blob Data

This example updates an existing Document record. Depending on the contents of the request body, you can update the fields of the record, the binary data associated with it, or both.

If you want to update only the record fields, the request body doesn’t require the multipart content type.

Example request for updating binary data in a Document object

curl https://MyDomainName.my.salesforce.com/services/data/v64.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 binary data in a Document object

This request body represents the contents of UpdateDocument.json. This example updates the binary data of the record, as well as the Name and Keywords fields. If you want to update only the binary data, you can remove the lines of code with the Name and Keywords fields.

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.

--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 Status Codes and Error Responses.

Inserting a ContentVersion

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

Example usage for inserting a ContentVersion

curl https://MyDomainName.my.salesforce.com/services/data/v64.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 request body represents 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.

--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 Status Codes and Error Responses.

Using sObject Collections to Insert a Collection of Blob Records

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

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 Documents

curl https://MyDomainName.my.salesforce.com/services/data/v64.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 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.

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

{
    "allOrNone" : false,
    "records" :
    [
        {
            "attributes" :
            {
                "type" : "Document",
                "binaryPartName": "binaryPart1",
                "binaryPartNameAlias": "Body"
            },
            "Description" : "Marketing Brochure",
            "FolderId" : "005xx000001Svs4AAC",
            "Name" : "Brochure",
            "Type" : "pdf"
        },
        {
            "attributes" :
            {
                "type" : "Document",
                "binaryPartName": "binaryPart2",
                "binaryPartNameAlias": "Body"
            },
            "Description" : "Pricing Overview",
            "FolderId" : "005xx000001Svs4AAC",
            "Name" : "Pricing",
            "Type" : "pdf"
        }
    ]
}

--boundary_string
Content-Disposition: form-data; name="binaryPart1"; filename="Brochure.pdf"
Content-Type: application/pdf

Binary data goes here.
--boundary_string
Content-Disposition: form-data; name="binaryPart2"; filename="Pricing.pdf"
Content-Type: application/pdf

Binary data goes here.
--boundary_string--

Example response body for creating Documents

On success, the IDs of the new Documents are returned.

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

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 request body.
• Must be specified in the Content-Type header of multipart request.
• Can be up to 70 characters.
• Can’t be a string value that appears anywhere in any part of the request body.
• Includes a two hyphen (--) prefix for the first boundary string.
• Includes a two hyphen (--) suffix for the last boundary string.

Content-Disposition Header

• Required in each part of the request body.
• Must have form-data as a value and a name attribute.
  • In the non-binary part of the request body, use any value for the name attribute.
  • For single documents, in the binary part of the request body, use the name attribute to specify the name of the blob data field for the object. For example, the name of the blob data field for the Document object is Body.
  • For documents inserted or updated using sObject Collections, use the name attribute in each binary part of the request body to specify a unique identifier for that part. These identifiers are referenced by the non-binary part of the request body.
• Must contain a filename attribute for the binary part that represents the name of the local file.

Content-Type Header

• Required in each part of the multipart request body.
• Supports the application/json and application/xml content types for the non-binary part of the multipart request body.
• Supports any content type for the binary part of the multipart request body.

New Line

A new line must be added between the header and the data for each part of the multipart request body. As you can see in the examples, a new line separates the Content-Type and Content-Disposition headers from the JSON or binary data.