Newer Version Available
Inputs and Binary File Upload Examples
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 these 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.
To upload multiple binary files in the same call, see Batch Resource.
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. |
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" | To post a feed element with a binary file (in version 35.0 and earlier), the value of name must be "feedElement". |
| form-data; name="comment" | To post a comment with a binary file, the value of name must be "comment". | |
| form-data; name="photo" | To upload an employee, user, or group photo, the value of name must be "photo". | |
| form-data; name="file" | To upload a file to the Files home or an external repository, the value of name must be "file". | |
| form-data; name="folderItem" | To upload a file to a folder, the value of name must be "folderItem". | |
| form-data; name="ManagedContentInputParam" | To upload a piece of managed content, the value of name must be "ManagedContentInputParam". | |
| form-data; name="ManagedContentVariantInputParam" | To update a managed content variant, the value of name must be "ManagedContentVariantInputParam". |
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". | |
| form-data; name="audioFileData" filename=string | To upload an audio file, the value of name must be "audioFileData". If you specify this value, don’t specify recordingURL or name or the request will fail. | |
| form-data; name="contentData" filename=string | To upload a piece of managed content or update a managed content variant, the value of name must be "contentData". | |
| Content-Type | application/octet-stream; charset=ISO-8859-1 | The media type and character set of the binary file. |
Post a feed element with a binary file (version 35.0 and earlier)
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!...' --insecure1POST /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)
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' --insecure1POST /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--Post a comment with a binary file
1curl -H "X-PrettyPrint: 1" -F 'json={ "body":{ "messageSegments":[ { "type":"Text", "text":"Here's another receipt." } ] }, "capabilities":{ "content":{ "title":"receipt2" } } };
2type=application/json' -F "feedElementFileUpload=@receipt2.txt;type=application/octet-stream"
3-X POST https://instance_name/services/data/v64.0/chatter/feed-elements/0D5RR0000004Grx/capabilities/comments/items
4-H 'Authorization: OAuth 00DRR0000000N0g!ARoAQB...' --insecure1POST /services/data/v64.0/chatter/feed-elements/0D5RR0000004Grx/capabilities/comments/items HTTP/1.1
2Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.
3OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyae
4Accept: application/json
5User-Agent: Jakarta Commons-HttpClient/3.0.1
6Host: instance_name
7Content-Length: 978
8Content-Type: multipart/form-data; boundary=F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI
9
10--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI
11Content-Disposition: form-data; name="json"
12Content-Type: application/json; charset=UTF-8
13
14{
15 "body":{
16 "messageSegments":[
17 {
18 "type":"Text",
19 "text":"Here's another receipt."
20 }
21 ]
22 },
23 "capabilities":{
24 "content":{
25 "title":"receipt2"
26 }
27 }
28}
29
30--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI
31Content-Disposition: form-data; name="feedElementFileUpload"; filename="receipt2.txt"
32Content-Type: application/octet-stream; charset=ISO-8859-1
33
34...contents of receipt2.txt...
35
36--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI--Post multiple comments with binary files
Include the request body of each subrequest in the richInput properties.
Also include information about the binary parts in the binaryPartName and binaryPartNameAlias properties.
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/v64.0/connect/batch
8-H 'Authorization: OAuth 00DD00000007HoR!...' --insecure1https://instance_name/services/data/v64.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":"/v64.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":"/v64.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
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/v64.0/connect/user-profiles/me/photo
4 -H 'Authorization: OAuth 00DRR0000000N0g!ARoAQFRi_gBqZhajAX22MNuLrrE2Xk...'
5 --insecure1POST /services/data/v64.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
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/v64.0/connect/files/users/me
4-H 'Authorization: OAuth 00DRR0000000N0g!...' --insecure1POST /services/data/v64.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
1curl -H "X-PrettyPrint: 1" -F 'json={"itemTypeId" : "L3NpdGVzL0FDRVRfRklMRUNPTk5FQ1RfSU5U:5f33e0f4-b33c-4127-b9e4-dd5a73dd2f1b:0c847e7c-d4a2-4136-bfda-c468fae2d087:0x0101","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/v64.0/connect/content-hub/repositories/
50XCxx000000002CGAQ/folders/folder:0Bz0nXuFg43SiflFNdFNIaUJrY2hQaHVIVHMxYVpHd2ZHeXphTW83TElzcE84RUJ2Q3Q4Rm8/
6items
7-H 'Authorization: OAuth 00DRR0000000N0g!...' --insecure1POST /services/data/v64.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" : "L3NpdGVzL0FDRVRfRklMRUNPTk5FQ1RfSU5U:5f33e0f4-b33c-4127-b9e4-dd5a73dd2f1b:0c847e7c-d4a2-4136-bfda-c468fae2d087:0x0101",
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
1curl --location --request POST 'https://instance_name/services/data/v64.0/voicecalls/0LQB00000001BqU/audio_upload' \
2--header 'Authorization: Bearer 00DR0000000H1C0!ARYAQA2lbJjcFU6PMnH.cFInsqFQvFkqDlnzQTUEUgjPJ6_gVHo7ZdGCFnFTYt3AWuKLFz2ahVdsd1pS9ENozHfrONLI_EQa' \
3--form 'audioFileData=@/Users/v.dodeja/Desktop/recordingservlet.mp3'Upload an audio file from a third-party vendor
1curl --location --request POST 'https://instance_name/services/data/v64.0/voicecalls/0LQB00000001BqU/audio_upload' \
2--header 'Authorization: Bearer 00DR0000000H1C0!ARYAQA2lbJjcFU6PMnH.cFInsqFQvFkqDlnzQTUEUgjPJ6_gVHo7ZdGCFnFTYt3AWuKLFz2ahVdsd1pS9ENozHfrONLI_EQa' \
3--form 'recordingURL=@/restapi/v1.0/account/401452676008/recording/401786818008/content' 'name=@namedCredential'Upload a piece of managed content
1POST /connect/cms/contents/
2Content-Type: multipart/form-data; boundary=FILE
3
4--FILE
5Content-Disposition: form-data; name="ManagedContentInputParam";
6Content-Type: application/json; charset=UTF-8
7
8{
9"contentSpaceOrFolderId":"0Zuxx00000003M5CAI",
10"title":"title",
11"contentType":"sfdc_cms__image",
12"urlName":"testUrl",
13"contentBody" : {
14 "sfdc_cms:media": {
15 "source": {
16 "type": "file" }
17}
18}
19
20--FILE
21Content-Disposition: form-data; name="contentData"; fileName="Image.jpg"
22Content-Type: application/octet-stream; charset=ISO-8859-1
23
24<Binary File Data>
25
26\n
27--FILE--Update a managed content variant
1PUT /connect/cms/contents/variants/9Psxx00000004WsCAI
2Content-Type: multipart/form-data; boundary=FILE
3
4--FILE
5Content-Disposition: form-data; name="ManagedContentVariantInputParam";
6Content-Type: application/json; charset=UTF-8
7
8{
9"title":"title",
10"urlName":"testUrl",
11"contentBody" : {
12 "sfdc_cms:media": {
13 "source": {
14 "type": "file" }
15}
16}
17
18--FILE
19Content-Disposition: form-data; name="contentData"; fileName="Image.jpg"
20Content-Type: application/octet-stream; charset=ISO-8859-1
21
22<Binary File Data>
23
24\n
25--FILE--