Salesforce REST API Upload File: Step-by-Step With Code and Size Limits

AM
Anita M.
Distribution Center Manager
★★★★★★★★★★
4.5/5 · 9/21/2026

Time-Saving Integration with Excellent Support

"I like that APPSeCONNECT saves us a lot of time by automating the import of sales orders from Shopify into SAP Business One. It helps in updating business partner contact information, which is great because before we had to hand-type the orders, but now it's all imported smoothly."

Read more APPSeCONNECT Reviews
Article banner: Salesforce REST API Upload File
Default author profile photoPritam Sen7 min read

To upload a file with the Salesforce REST API, send a POST request to /sobjects/ContentVersion with the file, a Title and PathOnClient. Salesforce creates the ContentVersion and its ContentDocument. Then link the file to a record with ContentDocumentLink, or set FirstPublishLocationId in the first call. Multipart requests accept files up to 2 GB.

Salesforce Files is the modern way to store, share, and link documents inside the CRM. The legacy Attachments object is no longer the right path for new builds. The REST API gives developers a clean way to push files into Salesforce from any backend, mobile app, or integration platform.

This guide walks through the three objects involved (ContentVersion, ContentDocument, ContentDocumentLink), the exact API calls in order, how to test in Postman, and where teams get stuck.

Uploading files in Salesforce is a common requirement for businesses. Documents like invoices, receipts, catalogs, agreements, etc. are often shared with prospects, clients, and customers. And many times, the built-in file upload feature isn’t enough. In such cases, using the REST API provides a programmatic and efficient method for file uploads. So our step-by-step guide will show you exactly how to do it by using the Salesforce file upload API.

Key Components of Salesforce Files

Salesforce Files is a modern file management solution within the Salesforce ecosystem. It’s designed to store, share, and manage files in a secure and organized way. It replaces the older “Attachments” functionality, providing enhanced capabilities and better integration with Salesforce’s collaborative and automation tools.

Key components include:

  1. ContentVersion: Represents a version of a file. Each time a file is updated, a new ContentVersion record is created. It contains information such as:ContentLocation: Represents the origin of the document. Valid values are:
    i. “S”: S-Document is located within the Salesforce.
    ii. “E”: E-Document is located outside the Salesforce.
    iii. “L”: L-Document is located on a social network and accessed via Social Customer Service.PathOnClient: Represents the path of the document. You must specify the complete path, including the path extension, for the document to be visible in the Preview tab.VersionData: It contains the file content.Title: It represents the name of the file.
  2. ContentDocument: Acts as the reference for the file. A single ContentDocument can have multiple versions.
  3. ContentDocumentLink: Connects a ContentDocument to one or more Salesforce records (e.g., accounts, opportunities). It contains the following key fields:ContentDocumentId: Refers to the file (ContentDocument) being shared.LinkedEntityId: Represents the ID of the record with which the file is associated.ShareType: Indicates the level of access granted, such as Viewer, Collaborator, or Inferred permission based on record sharing.Visibility: Defines who can view the file. Possible values are:
    i. AllUsers: Available to all users with permission to view the file.
    ii. InternalUsers: Restricted to internal users only.
    iii. SharedUsers: Limited to users who have access to the record or feed where the file is shared.
Field
Values
Meaning
ShareType
V (Viewer), C (Collaborator), I (Inferred)
The access users get to the file through the linked record; I follows the record's sharing
Visibility
AllUsers, InternalUsers, SharedUsers
Who can see the file: everyone with access, internal users only, or users the file is shared with

How to Upload Documents in Salesforce Files Using REST API?

Now let’s go through the steps to upload Salesforce Files using REST API.

Watch the video below and follow the step-by-step guide to upload Salesforce Files successfully.

Here’s a detailed breakdown of all the steps involved in uploading files with REST API.

Step 1: Connect Salesforce to Postman

We’ll use Postman as the third-party tool for interacting with the Salesforce file upload API.

Check this guide for the detailed process: Connecting Salesforce with Postman

Step 2: Upload the file to Salesforce

Use the POST Request for ContentVersion API to upload the file as shown in the image below.

  • In the JSON request, enter appropriate values for “Title”, “PathOnClient”, “ContentLocation”, and “VersionData”.
  • For this REST API upload file example, the title of our file is “Casings and Instruments”. Content location is inside Salesforce and the path for the PDF file is specified. Finally, you can see the encrypted version data, which represents the content of the document.
  • Once done, click on Send. If the request is successful, you should get a response as follows, indicating the Salesforce upload file operation was successful.

Step 3: Fetch the ContentDocumentID

In the above response, copy the ContentVersion “id” value. Next, run the SOQL Query (GET request) with SELECT syntax as shown, and paste the copied ID at the end. Then click on Send.

The response request will give you the ContentDocumentID value as shown below.

Step 4: View the Uploaded File

Copy the ContentDocumentID and search for it in Salesforce. It should show up in the Files section, and you can check the preview.

Step 5: Assign the Uploaded File to a Salesforce Record

Next, to assign this file to a specific record (like an account or opportunity) in Salesforce, we’ll use the POST request with ContentDocumentLink API.

In the body of the JSON request, you’ll have to fill in details for the following objects:

  • ContentDocumentID: Paste the ContentDocumentID you fetched in the earlier steps.
  • LinkedEntityID: Paste the ID of the Opportunity to which you want to assign this file.
  • Visibility: Choose a suitable visibility level.

Then click on Send.

When you get a success response, the file will be assigned to the opportunity. So go back and check the same in the CRM.

Following these steps, we can create a document in Salesforce by using REST API.

Salesforce REST API Upload File Examples: JSON and Multipart

Salesforce accepts two request formats. Use JSON with base64 for small files and multipart for anything larger. Both examples use API version 68.0; replace MyDomainName and the token with your own.

Option 1: JSON with base64 (files up to 37.5 MB encoded)

http
POST https://MyDomainName.my.salesforce.com/services/data/v68.0/sobjects/ContentVersion
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "Title": "Casings and Instruments",
  "PathOnClient": "Casings and Instruments.pdf",
  "ContentLocation": "S",
  "FirstPublishLocationId": "006XXXXXXXXXXXXXXX",
  "VersionData": "<base64-encoded file content>"
}

Option 2: multipart (files up to 2 GB)

bash
curl https://MyDomainName.my.salesforce.com/services/data/v68.0/sobjects/ContentVersion \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: multipart/form-data; boundary=boundary_string" \
  --data-binary @NewContentVersion.txt

The body file holds a JSON part named entity_content with Title and PathOnClient, then a binary part named VersionData with the file and a filename attribute.

Get the ContentDocumentId for the new version

http
GET /services/data/v68.0/query?q=SELECT+ContentDocumentId+FROM+ContentVersion+WHERE+Id='068XXXXXXXXXXXXXXX'
json
POST /services/data/v68.0/sobjects/ContentDocumentLink
{
  "ContentDocumentId": "069XXXXXXXXXXXXXXX",
  "LinkedEntityId": "006XXXXXXXXXXXXXXX",
  "ShareType": "V",
  "Visibility": "AllUsers"
}

New version of an existing file: ContentVersion records cannot be updated. To replace a file, insert a new ContentVersion with the existing ContentDocumentId and a ReasonForChange; Salesforce keeps the version history.

Salesforce REST API File Size Limits

Upload method
Limit
Use it for
JSON body with base64 VersionData
37.5 MB of base64 data (50 MB of text per request)
Small files from scripts, Flows calling out, quick tests in Postman
Multipart request to sObject Basic Information or sObject Rows, ContentVersion
2 GB per file
Large PDFs, images, video and exports
Multipart request to other standard objects with a blob field (for example Document)
500 MB per file
Legacy objects; prefer Salesforce Files
Multipart request to sObject Collections
500 MB total across all files in one request
Uploading several files in one call

Source: Salesforce REST API Developer Guide, "Insert or Update Blob Data". File storage counts against your org’s file storage allocation, so check storage before a bulk upload.

Salesforce Files vs Attachments: Know the Difference

Attachments are an older method for storing files in Salesforce. And while they remain functional in the CRM, they are not recommended for new implementations.

Salesforce Files, the newer system, offers superior features like version control and enhanced sharing options.

Users must be cautious to ensure their file uploads are categorized as Files, not Attachments, especially when managing legacy records or migrating data.

Salesforce API Changes That Affect File Uploads in 2026 and 2027

Date
Change
What to do
Summer '25
API versions 21.0 to 30.0 retired
Calls to /services/data/v30.0 and older fail; use a current version such as v68.0
Spring '26
New connected apps can no longer be created; External Client Apps replace them
Create an External Client App for new upload integrations and use OAuth 2.0
1 Dec 2026
SOAP login() requires the Use Any API Auth permission
Upload scripts that get a session ID from SOAP login() need the permission or a move to OAuth
Summer '27
SOAP login() retired in API versions 31.0 to 64.0
Replace username and password sessions with an OAuth 2.0 flow such as client credentials or JWT bearer

Why use REST API to upload files in Salesforce?

When sales reps and Salesforce users need to upload single files, the native upload feature in the CRM is enough.

But in the following scenarios, you’ll need REST APIs for file uploads:

Batch processing of bulk uploads

REST API supports bulk operations, so you can upload multiple files automatically. It also enables dynamic uploads from users in real-time scenarios, such as uploading attachments to cases, leads, or custom objects.

Automate file uploads with APIs

Manual file uploads can be time-consuming and prone to errors. Utilizing Salesforce’s APIs, you can automate file uploads as part of your workflows. Further, you can trigger uploads by specific events, saving time and ensuring consistency.

Integrate with Other Systems

Businesses using Salesforce usually integrate the CRM with other systems such as ERP or warehouse management software. A REST API to upload files allows programmatic uploads from these systems directly to Salesforce. It eliminates manual intervention while ensuring all records stay in sync.

Centralized File Management

With Salesforce file upload API, you can enforce rules for organizing and linking files. For instance, you can automatically attach files to the correct records, assign them to specific folders, or apply metadata tags, ensuring a more organized file management system.

Error Handling and Validation

REST API provides detailed responses for each operation including error codes and messages. It also gives you greater control over the upload process, facilitating error handling for issues like file size limits, unsupported formats, or record associations.

These features and scenarios are particularly useful for:

  • Salesforce developers who want to upload documents programmatically using Salesforce’s REST API.
  • System administrators who may need to configure or set up document uploads to Salesforce through API calls, especially when automating internal workflows.
  • System Integrators who need to connect various systems (like ERP) with Salesforce for different processes, including document management.
  • Salesforce users with custom requirements who want to extend Salesforce functionality and integrate documents in a way that Salesforce doesn’t provide natively.

What's Next: Automate Salesforce File Management Further with APPSeCONNECT

REST API significantly improves the efficiency of file uploads in Salesforce. But even this process can be further streamlined and fully automated with an integration platform like APPSeCONNECT.

A common scenario for Salesforce users is syncing data between their CRM and ERP systems. This data can include customer details, inventory updates, pricebooks sync, and even files and documents. With APPSeCONNECT, you can take this automation a step further, integrating multiple endpoints between Salesforce and your ERP.

If you’re looking for a simple solution to upload files more effectively, the steps outlined above will help you achieve that.

However, if you want to automate your entire business process by connecting Salesforce with your ERP and other systems, APPSeCONNECT is a low-code iPaaS solution.

To explore integration solutions for Salesforce, contact us or schedule a demo today!

Frequently Asked Questions

Use an OAuth 2.0 access token. Since Spring '26, new integrations are set up as External Client Apps rather than connected apps; existing connected apps keep working. Request a token with a flow such as client credentials or JWT bearer, then send it as a Bearer header on each upload call.

AM
Anita M.
Distribution Center Manager
★★★★★★★★★★
4.5/5 · 9/21/2026

Time-Saving Integration with Excellent Support

"I like that APPSeCONNECT saves us a lot of time by automating the import of sales orders from Shopify into SAP Business One. It helps in updating business partner contact information, which is great because before we had to hand-type the orders, but now it's all imported smoothly."

Read more APPSeCONNECT Reviews

Request for a personalized demo

Related Resources