Newer Version Available

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

Inputs and Binary File Upload Examples

Make HTTP POST, PATCH, and PUT requests using inputs and learn more about uploading binary files.

Using POST, PATCH, or PUT for Input

When you make a request using the HTTP POST, PATCH, and PUT methods, you can use request parameters or a request body. The request body can contain JSON or XML. If you pass resource-specific request parameters and a request body, the request parameters are ignored. Request parameters that aren’t specific to a resource, such as parameters in a bearer token URL and the _HttpMethod parameter, are processed along with the request body. Use bearer token parameters as they are. Don’t add or remove parameters.

To submit a request using request parameters, use a Content-Type header field with the value application/x-www-form-urlencoded.

To submit a request using a request body, use one of the following values in a Content-Type header field and in an Accept header field:

application/json
application/xml

Uploading Binary Files

To upload a binary file up to 2 GB (including headers), up to 75 MB for an external repository, or up to 512 MB for bulk conversations, send it as a body part in a multipart/form-data request. You can send the text of a comment (but not a post) as a JSON or XML rich input body part in the same multipart/form-data request. Alternately, you can choose to send that information in request parameters. If you pass both a rich input request body and request parameters, the request parameters are ignored.

In version 36.0 and later, you can’t create a feed post and upload a binary file in the same request. Upload files to Salesforce first, and then use the file IDs to attach one or more files to a feed post.

Important

To create a multipart/form-data request, in the head of the request, set the Content-Type HTTP header to multipart/form-data.

For information about HTTP headers, see W3C Form content types, and RFC 2388, which defines the multipart/form-data internet media type.

This table describes the HTTP headers and parameters required in the rich input body part of a multipart/form-data request:

HTTP Headers for Rich Input Body Part	Header Value and Parameters	Description
`Content-Disposition`	`form-data; name="json"` `form-data; name="xml"`	The request body for a post or comment. For JSON, the value of `name` use `"json"`. For XML, the value of `name` use `"xml"`.
`Content-Type`	`application/json; charset=UTF-8` `application/xml; charset=UTF-8`	The data format and character set of the request body. For JSON, the value must be `application/json`. For XML, the value must be `application/xml`.

HTTP Headers for Rich Input Body Part

Header Value and Parameters

Description

Content-Disposition

form-data; name="json"

form-data; name="xml"

The request body for a post or comment.

For JSON, the value of name use "json".

For XML, the value of name use "xml".

Content-Type

application/json; charset=UTF-8

application/xml; charset=UTF-8

The data format and character set of the request body.

For JSON, the value must be application/json.

For XML, the value must be application/xml.

Web browsers are typically incapable of making multipart requests when the non-binary parts, such as rich input bodies, have their own Content-Type. To work around this issue, specify a certain Content-Disposition name and Salesforce can read the Content-Type of the rich input part. (You don’t have to specify a Content-Type for the rich input body.)

Tip

This table describes the HTTP headers and parameters required in the rich input body part of a multipart/form-data request from a web browser:

HTTP Headers for Rich Input Body Part from Web Browser	Header Value and Parameters	Description
`Content-Disposition`	`form-data; name="feedElement"` `form-data; name="comment"` `form-data; name="photo"` `form-data; name="file"`	To post a feed element with a binary file (in version 35.0 and earlier), the value of `name` must be `"feedElement"`. To post a comment with a binary file, the value of `name` must be `"comment"`. To upload an employee, user, or group photo, the value of `name` must be `"photo"`. To upload a file to the Files home or an external repository, the value of `name` must be `"file"`.

HTTP Headers for Rich Input Body Part from Web Browser

Header Value and Parameters

Description

Content-Disposition

form-data; name="feedElement"

form-data; name="comment"

form-data; name="photo"

form-data; name="file"

To post a feed element with a binary file (in version 35.0 and earlier), the value of name must be "feedElement".

To post a comment with a binary file, the value of name must be "comment".

To upload an employee, user, or group photo, the value of name must be "photo".

To upload a file to the Files home or an external repository, the value of name must be "file".

This table describes the HTTP headers and parameters required in the binary upload body part of a multipart/form-data request:

HTTP Headers for Binary Upload Body Part	Header Value and Parameters	Description
`Content-Disposition`	`form-data; name="feedElementFileUpload"; filename=string`	To post a feed element with a binary file (in version 35.0 and earlier), the value of `name` must be `"feedElementFileUpload"`. To post a comment with a binary file, the value of `name` must be `"feedElementFileUpload"`.
	`form-data; name="fileUpload" filename=string`	To upload a user or group photo, the value of `name` must be `"fileUpload"`.
	`form-data; name="fileData" filename=string`	To upload a file to the Files home or to upload a file to an external repository, the value of `name` must be `"fileData"`. Specify a `filename` parameter and value. However, Salesforce uses the value of the `title` property of the File Input or the metadata of the Files Connect Item Input as the file name, not the value of the `filename` parameter. Note
	`form-data; name="audioFileData" filename=string`	To upload an audio file, the value of `name` must be `"audioFileData"`.
`Content-Type`	`application/octet-stream; charset=ISO-8859-1`	The media type and character set of the binary file.

Spacing and carriage returns and line feeds (CRLF) are important. For example, this line requires spaces: Content-Disposition: form-data; name="feedItemFileUpload"; title="2012_q1_review.ppt". If you had used CRLF instead of spaces, you would have received an error.

Note

Post a feed element with a binary file (version 35.0 and earlier)

This example uses the /chatter/feed-elements resource to post a new feed item (which is a type of feed element), upload a binary file, and attach it to the new feed item. This example uses cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={ "body":{ "messageSegments":[ { "type":"Text", "text":"Please accept this receipt." } ] }, 
2"capabilities":{ "content":{ "description":"Receipt for expenses", "title":"receipt.pdf" } }, "feedElementType":"FeedItem", "subjectId":"005RR000000DmOb" };
3type=application/json' -F "feedElementFileUpload=@receipt.pdf;type=application/octet-stream"
4 -X POST https://instance_name/services/data/v35.0/chatter/feed-elements 
5-H 'Authorization: OAuth 00DRR0000000N0g!...' --insecure

Here is the same example in a different format so you can see the request body parts.

1POST /services/data/v35.0/chatter/feed-elements HTTP/1.1
2Authorization: OAuth 00DRR0000000N0g!...
3User-Agent: Jakarta Commons-HttpClient/3.0.1
4Host: instance_name
5Content-Length: 845
6Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
7Accept: application/json
8
9--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
10Content-Disposition: form-data; name="json"
11Content-Type: application/json; charset=UTF-8
12
13{
14   "body":{
15      "messageSegments":[
16         {
17            "type":"Text",
18            "text":"Please accept this receipt."
19         }
20      ]
21   },
22   "capabilities":{
23      "content":{
24         "description":"Receipt for expenses",
25         "title":"receipt.pdf"
26      }
27   },
28   "feedElementType":"FeedItem",
29   "subjectId":"005RR000000DmOb"
30}
31
32--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
33Content-Disposition: form-data; name="feedElementFileUpload"; filename="receipt.pdf"
34Content-Type: application/octet-stream; charset=ISO-8859-1
35
36...contents of receipt.pdf...
37
38--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

Post a batch of feed elements with binary files (version 35.0 and earlier)

This example uses the /chatter/feed-elements/batch resource to post a batch of feed elements, upload two binary files, and attach them to the feed elements in the batch. Include the information about the binary parts in the request body. This example uses cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={"inputs":[{"binaryPartNames":["bin1"], "richInput":{"subjectId":"me","body":{
2"messageSegments":[{"type":"Text","text":"Please accept this receipt"}]},"capabilities": {"content" : {"description": "Receipt for expenses", "title":"receipt.pdf"}},"feedElementType":"FeedItem"}},
3{"binaryPartNames":["bin2"],"richInput":{"subjectId":"me","body":{"messageSegments":[{"type":"Text","text":"Post Number 2"}]},
4"capabilities": {"content" : {"description": "Receipt for expenses", "title":"receipt2.pdf"}},"feedElementType":"FeedItem"}}]};type=application/json' 
5-F "bin1=@/Users/jsmith/Desktop/receipt.pdf;type=application/octet-stream" -F "bin2=@/Users/jsmith/Desktop/receipt2.pdf;type=application/octet-stream" 
6-X POST https://instance_name/services/data/v35.0/chatter/feed-elements/batch 
7-H 'Authorization: OAuth 00DD00000007HoR44QATPNzhzYEJBfU' --insecure

Here is the same example formatted to show the request body parts.

1POST /services/data/v35.0/chatter/feed-elements/batch HTTP/1.1
2Authorization: OAuth 00DRR0000000N0g!...
3User-Agent: Jakarta Commons-HttpClient/3.0.1
4Host: instance_name
5Content-Length: 845
6Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
7Accept: application/json
8
9--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
10Content-Disposition: form-data; name="json"
11Content-Type: application/json; charset=UTF-8
12
13{
14  "inputs": [
15    {
16      "binaryPartNames": [
17        "bin1"
18      ],
19      "richInput": {
20        "subjectId": "me",
21        "body": {
22          "messageSegments": [
23            {
24              "type": "Text",
25              "text": "Please accept this receipt"
26            }
27          ]
28        },
29        "capabilities": {
30          "content": {
31            "description": "Receipt for expenses",
32            "title": "receipt.pdf"
33          }
34        },
35        "feedElementType": "FeedItem"
36      }
37    },
38    {
39      "binaryPartNames": [
40        "bin2"
41      ],
42      "richInput": {
43        "subjectId": "me",
44        "body": {
45          "messageSegments": [
46            {
47              "type": "Text",
48              "text": "Post Number 2"
49            }
50          ]
51        },
52        "capabilities": {
53          "content": {
54            "description": "Receipt for expenses",
55            "title": "receipt2.pdf"
56          }
57        },
58        "feedElementType": "FeedItem"
59      }
60    }
61  ]
62}
63
64--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
65Content-Disposition: form-data; name="bin1"; filename="receipt.pdf"
66Content-Type: application/octet-stream; charset=ISO-8859-1
67
68...contents of receipt.pdf...
69
70
71--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
72Content-Disposition: form-data; name="bin2"; filename="receipt2.pdf"
73Content-Type: application/octet-stream; charset=ISO-8859-1
74
75...contents of receipt2.pdf...
76
77--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

The binary part names in the binaryPartNames properties must match the binary part names in the name properties of the binary request parts.

Note

Post multiple comments with binary files

This example is a generic batch request to /connect/batch that contains two subrequests. Each subrequest comments on a feed item and uploads a binary file to the comment.

Include the request body of each subrequest in the richInput properties.

Also include information about the binary parts in the binaryPartName and binaryPartNameAlias properties.

Here is the cURL example.

1curl -H "X-PrettyPrint: 1" -F 'json={ "haltOnError":true, "batchRequests":[ { "url":"/v33.0/chatter/feed-elements/0D5D0000000YG0N/capabilities/comments/items", 
2"method":"Post", "binaryPartName":"binaryPart1", "binaryPartNameAlias":"feedElementFileUpload", "richInput":{ "body":{ "messageSegments":[ { "type":"Text", "text":"Check out this file, it may help." } ] },
3 "capabilities":{ "content":{ "title":"Presentation1.txt" } } } }, { "url":"/v33.0/chatter/feed-elements/0D5D0000000YG0M/capabilities/comments/items", 
4"method":"Post", "binaryPartName":"binaryPart2", "binaryPartNameAlias":"feedElementFileUpload", "richInput":{ "body":{ "messageSegments":[ { "type":"Text", "text":"Check out this file, it may help." } ] },
5 "capabilities":{ "content":{ "title":"Presentation2.txt" } } } } ] };type=application/json' -F "binaryPart1=@/Users/jbleyle/Desktop/Presentation1.txt;type=application/octet-stream" 
6-F "binaryPart2=@/Users/jbleyle/Desktop/Presentation2.txt;type=application/octet-stream" 
7-X POST https://instance_name/services/data/v52.0/connect/batch 
8-H 'Authorization: OAuth 00DD00000007HoR!...' --insecure

Here is the multipart/form-data request body.

1https://instance_name/services/data/v52.0/connect/batch
2
3Authorization: OAuth 00DD0000000Jhd2!...
4Accept: application/json
5Host: instance_name
6Content-Type: multipart/form-data; boundary=123123
7
8--123123
9Content-Disposition: form-data; name="json"
10Content-Type: application/json
11
12{
13   "haltOnError":true,
14   "batchRequests":[
15      {
16         "url":"/v52.0/chatter/feed-elements/0D5D0000000YG0D/capabilities/comments/items",
17         "method":"Post",
18         "binaryPartName":"binaryPart1",
19         "binaryPartNameAlias":"feedElementFileUpload",
20         "richInput":{
21            "body":{
22               "messageSegments":[
23                  {
24                     "type":"Text",
25                     "text":"Check out this file, it may help."
26                  }
27               ]
28            },
29            "capabilities":{
30               "content":{
31                  "title":"Presentation1.txt"
32               }
33            }
34         }
35      },
36      {
37         "url":"/v52.0/chatter/feed-elements/0D5D0000000YG0H/capabilities/comments/items",
38         "method":"Post",
39         "binaryPartName":"binaryPart2",
40         "binaryPartNameAlias":"feedElementFileUpload",
41         "richInput":{
42            "body":{
43               "messageSegments":[
44                  {
45                     "type":"Text",
46                     "text":"Check out this file, it may help."
47                  }
48               ]
49            },
50            "capabilities":{
51               "content":{
52                  "title":"Presentation2.txt"
53               }
54            }
55         }
56      }
57   ]
58}
59
60
61--123123
62Content-Disposition: form-data; name="binaryPart1"; filename="Presentation1.txt"
63Content-Type: application/octet-stream; charset=ISO-8859-1
64Content-Transfer-Encoding: binary
65
66This is the content of file 1
67--123123
68Content-Disposition: form-data; name="binaryPart2"; filename="Presentation2.txt"
69Content-Type: application/octet-stream; charset=ISO-8859-1
70Content-Transfer-Encoding: binary
71
72This is the content of file 2
73--123123--

Upload and crop a user photo

This example uses the /connect/user-profiles/userId/photo resource to upload a user profile photo and crop it using cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={"cropX": "0", "cropY": "0", "cropSize": "200"};type=application/json'
2 -F "fileUpload=@myPhoto.jpg;type=application/octet-stream" 
3-X POST https://instance_name/services/data/v52.0/connect/user-profiles/me/photo
4 -H 'Authorization: OAuth 00DRR0000000N0g!ARoAQFRi_gBqZhajAX22MNuLrrE2Xk...'
5 --insecure

Here is the same example formatted to see the request body parts.

1POST /services/data/v52.0/connect/user-profiles/me/photo HTTP/1.1
2Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.
3OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyae
4User-Agent: Jakarta Commons-HttpClient/3.0.1
5Host: instance_name
6Content-Length: 543
7Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
8Accept: application/json
9
10--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
11Content-Type: application/json; charset=UTF-8
12Content-Disposition: form-data; name="json"
13
14{
15   "cropX" : "0",
16   "cropY" : "0",
17   "cropSize" : "200"
18}
19
20--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
21Content-Disposition: form-data; name="fileUpload"; filename="myPhoto.jpg"
22Content-Type: application/octet-stream; charset=ISO-8859-1
23
24...contents of myPhoto.jpg...
25
26--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

Upload a file to the Files home

This example uses the /connect/files/users/userId resource to upload a file to the Files home using cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={"title":"BoatPrices"};type=application/json' 
2-F "fileData=@BoatPrices.pdf;type=application/octet-stream" 
3-X POST https://instance_name/services/data/v52.0/connect/files/users/me 
4-H 'Authorization: OAuth 00DRR0000000N0g!...' --insecure

Here is the same example formatted to see the request body parts.

1POST /services/data/v52.0/connect/files/users/me
2
3Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.
4OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyae
5User-Agent: Jakarta Commons-HttpClient/3.0.1
6Host: instance_name
7Content-Length: 489
8Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
9Accept: application/json
10
11--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
12Content-Type: application/json; charset=UTF-8
13Content-Disposition: form-data; name="json"
14
15{
16   "title":"BoatPrices"
17}
18
19--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
20Content-Disposition: form-data; name="fileData"; filename="BoatPrices.txt"
21Content-Type: application/octet-stream; charset=ISO-8859-1
22
23...contents of BoatPrices.txt...
24
25--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

Upload a file to an external repository

This example uses the /connect/content-hub/repositories/repositoryId/folders/repositoryFolderId/items resource to upload a file to an external repository using cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={"itemTypeId" : "file","fields" : [{"name" : "name","value" : "Content Hub Simple Create Specs"},
2{"name" : "description","value" : "Document explaining the various connect api endpoints required for simple create"}]};type=application/json' 
3-F "fileData=@BoatPrices.pdf;type=application/text/plain" 
4-X POST https://instance_name/services/data/v52.0/connect/content-hub/repositories/
50XCxx000000002CGAQ/folders/folder:0Bz0nXuFg43SiflFNdFNIaUJrY2hQaHVIVHMxYVpHd2ZHeXphTW83TElzcE84RUJ2Q3Q4Rm8/
6items 
7-H 'Authorization: OAuth 00DRR0000000N0g!...' --insecure

Here is the same example formatted to see the request body parts.

1POST /services/data/v52.0/connect/content-hub/repositories/0XCxx000000002CGAQ/
2folders/folder:0Bz0nXuFg43SiflFNdFNIaUJrY2hQaHVIVHMxYVpHd2ZHeXphTW83TElzcE84RUJ2Q3Q4Rm8/items
3
4Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.
5OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyae
6User-Agent: Jakarta Commons-HttpClient/3.0.1
7Host: instance_name
8Content-Length: 489
9Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
10Accept: application/json
11
12--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
13Content-Type: application/json
14Content-Disposition: form-data; name="json"
15
16{
17   "itemTypeId" : "file",
18   "fields" : [
19   {
20      "name" : "name",
21      "value" : "Items Sharepoint 012.png"
22   },
23   {
24      "name" : "description",
25      "value" : "This is a test file"
26   }]
27}
28
29--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
30Content-Disposition: form-data; name="fileData"; filename="items_Sharepoint_012.png"
31Content-Type: image/png
32
33...PNG...
34
35--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

Upload an audio file

This example uses the /voicecalls/voiceCallId/audio_upload resource to upload an audio file using cURL.

1curl --location --request POST 'https://instance_name/services/data/v52.0/voicecalls/0LQB00000001BqU/audio_upload' \
2--header 'Authorization: Bearer 00DR0000000H1C0!ARYAQA2lbJjcFU6PMnH.cFInsqFQvFkqDlnzQTUEUgjPJ6_gVHo7ZdGCFnFTYt3AWuKLFz2ahVdsd1pS9ENozHfrONLI_EQa' \
3--form 'audioFileData=@/Users/v.dodeja/Desktop/recordingservlet.mp3'

Connect REST API Developer Guide

Inputs and Binary File Upload Examples

Using POST, PATCH, or PUT for Input

Uploading Binary Files

Post a feed element with a binary file (version 35.0 and earlier)

Post a batch of feed elements with binary files (version 35.0 and earlier)

Post a comment with a binary file

Post multiple comments with binary files

Upload and crop a user photo

Upload a file to the Files home

Upload a file to an external repository

Upload an audio file