Salesforce File Upload Explained: Architecture, Object Relationships, and External Integration via REST APIs

Key Takeaways:

• Think in terms of file architecture, not just file uploads
  Salesforce Files is designed as a structured system—ContentVersion, ContentDocument, and ContentDocumentLink each serve a distinct purpose. Understanding this model upfront helps you design solutions that scale cleanly as file volume, versions, and sharing needs grow.
• Plan external access as part of your integration strategy
  Salesforce already provides secure, native options for exposing files outside the platform. Choosing between REST-based downloads and ContentDistribution URLs should be a deliberate architectural decision based on security, user experience, and access patterns.
• Match the sharing mechanism to the business use case
  Backend systems, batch processing, and regulated workflows benefit from authenticated REST access, while partner portals and customer-facing experiences are better served by controlled, expiring URLs. Aligning the approach early avoids rework and governance issues later.

File handling is a common requirement in Salesforce applications—whether you are uploading contracts, invoices, images, or documents from internal users or external systems.

While Salesforce provides powerful file management capabilities, understanding which objects are involved and how they relate to each other can initially feel complex.

This blog breaks down the Salesforce File architecture in a simple and structured way, helping you clearly understand:

• How file upload works in Salesforce
• Which objects are involved
• How are those objects related
• How files are shared and accessed

What Is “Salesforce Files”?

Salesforce uses a unified file system called Salesforce Files, which replaces the older Attachments and Documents model.

Key benefits of Salesforce Files:

• Files can be shared across multiple records
• Version control is built in
• Strong security and sharing model
• Files can be accessed via UI, Apex, and REST APIs

When you upload a file in Salesforce (from UI, Flow, Apex, or API), Salesforce automatically creates and links several related records behind the scenes.

Core Objects Involved in Salesforce File Upload

The Salesforce File system is mainly built on four core objects:

• ContentVersion
• ContentDocument
• ContentDocumentLink
• ContentDistribution (optional, for public sharing)

Let’s understand each step by step.

1️. ContentVersion – The Actual File Data

ContentVersion stores the actual file content and metadata.

What does ContentVersion contain?

• File binary data
• File name
• File type (PDF, PNG, DOCX, etc.)
• Version number
• File size
• Created date and owner

Important Concept

• Every upload creates at least one ContentVersion
• If a file is updated, a new ContentVersion is created (versioning)

Think of ContentVersion as “Each saved version of a file”

2️. ContentDocument – The File Identity

ContentDocument represents the logical file, independent of versions.

Key points:

• One ContentDocument can have multiple ContentVersions
• It acts as the parent container for versions
• The same ContentDocument can be linked to multiple records

Salesforce automatically creates a ContentDocument when the first ContentVersion is inserted.

Think of ContentDocument as “The file itself, across all versions.”

3. ContentDocumentLink – Connecting Files to Records

ContentDocumentLink defines where the file is shared.

This object links:

• A ContentDocument
• To another Salesforce record (Account, Contact, Case, Custom Object, etc.)

Important fields:

• LinkedEntityId → Record ID (Account, Case, etc.)
• ContentDocumentId → File
• ShareType → Viewer, Collaborator, or Inferred
• Visibility → InternalUsers, AllUsers, SharedUsers

A single file can have multiple ContentDocumentLink records, meaning:

• One file → many records

Think of ContentDocumentLink as “The bridge between a file and Salesforce records”

4️. ContentDistribution – Public File Access (Optional)

ContentDistribution is used when you want to:

• Share a file outside Salesforce
• Generate a public or semi-public URL

Common use cases:

• External portals
• Partner access
• Email attachments with download links
• External system integrations

It provides:

• Public download URL
• Preview URL
• Expiration settings
• Password protection (optional)

Think of ContentDistribution as “Making a Salesforce file accessible externally.”

Logical Architecture (Conceptual View)

Step-by-step flow:

• User uploads a file
• Salesforce creates a ContentVersion
• Salesforce creates a ContentDocument
• Salesforce creates a ContentDocumentLink to the record
• (Optional) A ContentDistribution is created for public access

Simple Real-World Example

Let’s say:

You upload “Contract.pdf” to an Account record

Behind the scenes:

• ContentVersion → Stores the actual PDF file
• ContentDocument → Represents “Contract.pdf.”
• ContentDocumentLink → Links the file to the Account
• ContentDistribution → Created only if you share it externally

If you upload a new version:

• New ContentVersion
• Same ContentDocument
• Same ContentDocumentLink

Salesforce Files vs Attachments (Legacy)

Salesforce strongly recommends using Files for all new development.

Security & Access Control

File access is controlled by:

• Record sharing
• ContentDocumentLink visibility
• File owner permissions
• ContentDistribution settings (for external access)

This ensures:

• Internal users see only permitted files
• External users access only what is shared

Our success story: See How Sigma’s Salesforce Services Modernized a Mission-Critical Government Verification System

Sharing Salesforce Files with External Systems Using REST API

In many real-world implementations, uploading files only inside Salesforce is not enough.
Often, we need to:

• Send uploaded files to an external system
• Allow partners or customers to preview or download files
• Share documents via secure URLs
• Integrate Salesforce with portals, mobile apps, or third-party platforms

Salesforce Files fully supports these use cases through REST APIs and public content URLs.

Let’s understand how this works step by step.

External Integration Architecture (Conceptual View)

Typical Flow:

• The file is uploaded to Salesforce
• Salesforce creates File-related records
• REST API fetches file metadata
• File download or preview URL is generated
• The external system consumes the file

Key Integration Approaches

There are two common ways to expose Salesforce files to external systems:

• Direct File Download via REST API
• Public File Sharing using ContentDistribution URLs

Let’s explore both.

Approach 1: Downloading Files via Salesforce REST API

This approach is used when:

• The external system is authenticated
• You want secure, controlled access
• You want to download the actual file binary

Step 1: Get the Latest ContentVersion

Every file upload creates a ContentVersion record.

Typical query:

Fetch the latest published version of the file using ContentDocumentId

Important fields:

• Id
• ontentDocumentId
• Title
• FileType
• ContentSize
• VersionNumber

Why ContentVersion?

• This object contains the actual file data
• REST API downloads work on ContentVersion

Step 2: Download the File Binary

Salesforce provides a direct REST endpoint to download file content:

What happens here?

• Salesforce returns the raw binary data
• External system saves or processes the file
• Works for PDFs, images, DOCX, etc.

This is best for:

• Backend integrations
• Secure system-to-system communication
• Large file processing

Things to Keep in Mind

• An API user must have file access
• API limits apply
• Best for authenticated integrations

Approach 2: Sharing Files Using ContentDistribution (Public URLs)

This is the most commonly used approach when:

• Files must be accessed outside Salesforce
• Preview and download should work in browsers
• Authentication should be minimal or optional

What Is ContentDistribution?

ContentDistribution allows Salesforce to generate:

• Public download URL
• Public preview URL
• Controlled access with expiration

These URLs can be safely shared with:

• External portals
• Email recipients
• Partner systems
• Mobile applications

Step 1: Create ContentDistribution Record

When a ContentDistribution record is created:

• Salesforce automatically generates URLs
• Links are tied to the file’s ContentVersion

Key fields:

• ContentVersionId
• DistributionPublicUrl
• ContentDownloadUrl
• ExpiryDate

Understanding the URLs

ContentDownloadUrl

• Downloads the file directly
• Works without Salesforce login (if public)
• Ideal for:
  External systems
  Automated file downloads
  UI previews
  Customer portals

These URLs are read-only and secure.

Real-World Example

Scenario:

A user uploads a signed contract in Salesforce, and the same contract must be visible in a Partner Portal.

Flow:

• File uploaded to Salesforce
• ContentVersion created
• ContentDocument linked to Account
• ContentDistribution generated
• External system stores:
  ContentDownloadUrl
• Partner clicks link → views or downloads the file

No Salesforce login required.

Security & Control Options

Salesforce gives strong control over external sharing:

Best practice:

• Always set an expiry date
• Regenerate links if compromised
• Avoid long-lived public URLs for sensitive documents

REST API Use Case Comparison

Best Practices:

✔ Always work with ContentDocumentId, not filenames
✔ Fetch latest ContentVersion before sharing
✔ Use ContentDistribution for UI-based access
✔ Avoid hardcoding API versions
✔ Handle file size and limits gracefully
✔ Secure URLs with expiry dates

Also, read Spring ’26: The Salesforce Updates That Matter

Complete Picture: Salesforce File + External Integration

By combining:

• Salesforce Files
• REST APIs
• ContentDistribution URLs

You can build:

• Custom file uploaders
• xternal document portals
• Partner systems
• Secure document sharing platforms

All are using standard Salesforce architecture.

Conclusion

Salesforce file handling may look complex at first glance, but once you understand the roles of ContentVersion, ContentDocument, ContentDocumentLink, and ContentDistribution, the architecture becomes logical and predictable. Each object has a clear responsibility—from storing the actual file data to managing versions, linking files to records, and securely sharing them outside Salesforce.

By leveraging Salesforce Files instead of legacy attachments, teams gain built-in versioning, flexible record sharing, and robust security controls. More importantly, Salesforce’s REST APIs and ContentDistribution URLs make it possible to extend file access beyond the platform—enabling integrations with portals, mobile apps, partner systems, and third-party applications without custom workarounds.

Whether you are building a simple file upload feature, designing an enterprise-grade integration architecture, or exposing documents securely to external users, Salesforce provides a scalable and standards-based foundation. With the right approach—working with ContentDocumentId, fetching the latest ContentVersion, and choosing the correct sharing method—you can confidently design file solutions that are secure, maintainable, and future-proof.

In short, mastering Salesforce Files is not just about uploading documents—it’s about enabling seamless document management and integration across your entire Salesforce ecosystem.

Designing, optimizing, or integrating Salesforce file management?

Sigma’s Salesforce services help you build secure, scalable file architectures—spanning uploads, record-level sharing, and REST-based external integrations. From modernizing legacy attachments to enabling enterprise-grade workflows, Sigma turns Salesforce Files into a business-ready asset.