Salesforce Attachment Object vs. Files: 2026 Guide
The Salesforce Attachment object is the legacy data model for a file attached to a record. In Lightning Experience, most new uploads are handled as Salesforce Files instead, using ContentDocument, ContentVersion, and ContentDocumentLink.
That distinction matters whenever you build an integration, migrate historical documents, report on files, or add customer evidence to a Salesforce Case. A query written for Attachment will not automatically return Salesforce Files, and a process that creates ContentVersion records will not create legacy Attachment records.
Quick answer: Use Salesforce Files for new solutions unless a specific legacy dependency requires the Attachment object. Query Attachment for historical legacy files, and query ContentDocumentLink with the related Files objects for modern files. Plan for both models during migrations and in organizations that have used Salesforce for many years.
1. What is the Salesforce Attachment object?
Attachment represents a file uploaded and attached to a parent Salesforce record. The file’s binary data is stored in the Body field, while ParentId identifies the record to which the file belongs.
Common Salesforce Attachment fields
The Attachment object uses a simple data model: one file record points to one parent record.
That simplicity is also its main limitation. It does not provide the richer versioning, sharing, library, and collaboration model available with Salesforce Files.
Example: query legacy Attachments on a Case
SELECT Id,
Name,
ContentType,
BodyLength,
ParentId,
CreatedDate
FROM Attachment
WHERE ParentId = '500XXXXXXXXXXXX'
ORDER BY CreatedDate DESC
To retrieve the binary content through an API, request the Attachment record’s Body blob resource using an authenticated Salesforce API call.
Avoid loading large Body values into Apex memory unless the use case and Salesforce governor limits have been carefully reviewed.
2. What are Salesforce Files?
Salesforce Files use a multi-object data model. The three objects most administrators and developers encounter are ContentDocument, ContentVersion, and ContentDocumentLink.
ContentDocument
ContentDocument represents the file as a logical document. It is the parent record that connects the file’s versions and sharing relationships.
Think of ContentDocument as the identity of the file.
ContentVersion
ContentVersion represents one version of the file. It contains version-specific information, including the uploaded binary data.
Creating the first ContentVersion normally causes Salesforce to create the related ContentDocument automatically.
Think of ContentVersion as the actual uploaded revision.
ContentDocumentLink
ContentDocumentLink represents the relationship between a file and the place where it is shared.
The linked entity may be:
- A Salesforce record
- A user
- A group
- A library
Think of ContentDocumentLink as the connection between a file and a Salesforce Case, Account, Opportunity, or another supported entity.
A single ContentDocument can be linked to more than one record without creating separate copies of the same file.
For a broader look at the record structure behind support workflows, including how Cases connect to Files, comments, and other related objects, read our guide to the Salesforce Case object.
3. Salesforce Attachment object vs. Salesforce Files
The legacy Attachment object and Salesforce Files differ in their data models, sharing capabilities, and recommended use cases.
Salesforce has stated that the legacy Notes & Attachments experience is being superseded by individual Notes and Salesforce Files features.
For new Salesforce architecture, Files should normally be the default.
4. How Salesforce Files relate to a Case
When a file is uploaded to a Salesforce Case, Salesforce typically creates or uses three records:
- A ContentDocument for the logical file
- A ContentVersion for the uploaded version
- A ContentDocumentLink whose LinkedEntityId is the Salesforce Case ID
The relationship can be represented as follows:
.png)
Salesforce Case IDs commonly begin with 500.
ContentDocument IDs commonly begin with 069.
ContentVersion IDs commonly begin with 068.
Files are only one part of the information stored around a support request. Our Salesforce Case Management guide explains how files, customer communication, routing, investigation, and resolution fit into the complete Case lifecycle.
Example: query Files linked to a Salesforce Case
SELECT ContentDocumentId,
ContentDocument.Title,
ContentDocument.FileType,
ContentDocument.LatestPublishedVersionId,
ShareType,
Visibility,
LinkedEntityId
FROM ContentDocumentLink
WHERE LinkedEntityId = '500XXXXXXXXXXXX'
ORDER BY SystemModstamp DESC
To retrieve details for the latest version, query the related ContentVersion record:
SELECT Id,
ContentDocumentId,
Title,
FileType,
FileExtension,
ContentSize,
VersionNumber,
IsLatest,
CreatedDate
FROM ContentVersion
WHERE ContentDocumentId = '069XXXXXXXXXXXX'
AND IsLatest = TRUE
The exact fields available and accessible depend on the Salesforce API version, permissions, sharing configuration, and file type.
5. How to upload a Salesforce File through Apex
To create a new Salesforce File, insert a ContentVersion record.
The FirstPublishLocationId field can associate the new file with a Salesforce record when it is created.
Id caseId = '500XXXXXXXXXXXX';
Blob fileBody = Blob.valueOf('Example content');
ContentVersion version = new ContentVersion(
Title = 'Customer issue details',
PathOnClient = 'customer-issue.txt',
VersionData = fileBody,
FirstPublishLocationId = caseId
);
insert version;
For production code:
- Validate the file type and size.
- Enforce object, field, and record access where required.
- Avoid accepting arbitrary binary content without security controls.
- Add appropriate error handling and automated tests.
- Consider asynchronous processing for integrations.
- Confirm whether the file must be shared beyond the first Salesforce record.
Uploading a new version of an existing file
To add a new version, insert another ContentVersion using the existing ContentDocumentId.
ContentVersion newVersion = new ContentVersion(
ContentDocumentId = existingContentDocumentId,
Title = 'Updated troubleshooting guide',
PathOnClient = 'troubleshooting-guide-v2.pdf',
VersionData = updatedBlob
);
insert newVersion;
Do not attempt to insert a ContentDocument directly as the standard starting point for a new file.
The normal Salesforce file creation pattern begins with ContentVersion.
Apex is one option, but it is not always the simplest one. See our guide to uploading files to Salesforce records for a comparison of the Files related list, Flow, Lightning components, APIs, and bulk migration methods.
6. Attachment API vs. Files API: which should an integration use?
Use the legacy Attachment API only when an integration must read, maintain, or migrate Attachment records that already exist.
Use the Salesforce Files model when an integration needs to:
- Upload a new file to a Case or another Salesforce record
- Maintain multiple file versions
- Share the same file with more than one record
- Use the Lightning Files experience
- Work with file libraries or modern sharing controls
- Build a solution aligned with Salesforce’s current file architecture
A mature Salesforce integration may need two separate read paths:
- Query Attachment for legacy file records.
- Query ContentDocumentLink for Salesforce Files.
If your application presents both types of files in one list, combining those records is the responsibility of the integration layer.
Salesforce stores legacy Attachments and Salesforce Files in different data models.
7. Understanding Attachment content type in Salesforce
For the Attachment object, ContentType stores the file’s MIME type.
Common examples include:
- application/pdf
- image/png
- image/jpeg
- text/plain
- video/mp4
Do not rely on a file extension or MIME type alone when making a security decision.
Client-provided file metadata can be incorrect or manipulated. Validate file content according to your security architecture and configure Salesforce file upload and download security settings appropriately.
In the Salesforce Files model, file information appears across fields such as FileType, FileExtension, and version-related metadata.
These values can support display and workflow logic, but the same security principle applies.
8. How to migrate Attachments to Salesforce Files
Migrating Salesforce Attachments involves more than copying file data.
You need to preserve the file, its relationship to a Salesforce record, its business context, access rules, and any relevant audit requirements.
Inventory the current data
Start by measuring:
- Total Attachment count
- Total storage consumption
- Parent object distribution
- File types and file sizes
- Owners and access patterns
- Attachments without valid parent records
- Duplicate files
- Regulatory and retention requirements
Define the target relationship
For every Attachment, determine which Salesforce record should become the first publish location.
Also decide whether the resulting Salesforce File must be shared with additional:
- Records
- Groups
- Users
- Libraries
Map Attachment fields
A common conceptual field mapping includes:
Audit fields cannot always be populated through a normal insert.
When historical timestamps and creators must be preserved, confirm the supported Salesforce migration approach before loading the data.
Test the migration in a sandbox
Use representative records in your migration tests, including:
- Large files
- Unusual file types
- Private or restricted records
- Experience Cloud or portal users
- Deleted or inactive owners
- Cases containing many files
- Files that must be visible to external customers
Validate access, not only record counts
A migration can have the correct number of records while still failing users.
Verify that:
- Internal users can find and preview migrated files.
- External users can see only the files they are permitted to access.
- Search and related lists work as expected.
- Existing integrations and reports have been updated.
- Automation does not create duplicate ContentDocumentLink records.
Customer-facing access requires particular care. When external or unauthenticated users need to submit evidence, follow the security controls described in our guide to Salesforce guest-user file uploads.
Update integrations and training
Update:
- API queries
- Reports
- Page layouts
- Automation
- User instructions
- Integration documentation
If employees continue uploading files through legacy paths, new data may remain split between the Attachment and Salesforce Files models.
9. Files, Attachments, and video on Salesforce Cases
A Salesforce File works well for documents, images, and other supporting evidence that belongs with a Case.
Video introduces additional considerations:
- File size and Salesforce storage consumption
- Browser playback experience
- External sharing and customer access
- Captions and accessibility
- Searchability and summaries
- Retention and deletion requirements
- Sensitive information displayed in the recording
- Reuse across support, product, and engineering teams
Uploading an MP4 as a Salesforce File may be sufficient for an occasional short recording.
For a repeatable video-support workflow, a dedicated video platform can provide a more structured recording, playback, and sharing experience.
Videolink adds video context to Salesforce records. An agent can record a walkthrough or request a recording from a customer while keeping the visual evidence connected to the Salesforce Case.
Videolink can also provide AI captions and summaries, as well as enterprise hosting and storage options, depending on the selected configuration.
This approach separates the Case record, which remains the operational source of truth, from the video delivery layer, which is optimized for recording, playback, access, and review.
When the evidence is difficult to explain in writing, the problem often begins earlier in the Case workflow. Our guide to Salesforce Case Comments explains when written customer communication is sufficient and when richer visual context may be more useful.
10. Decision guide
Choose the Salesforce Attachment object when:
- You must read or migrate historical Attachments.
- A legacy managed package has a documented dependency on Attachment records.
- You are maintaining an existing integration while planning its modernization.
Choose Salesforce Files when:
- You are building a new Salesforce solution.
- Users need modern file previews, versioning, sharing, or libraries.
- Files must be connected to one or more Salesforce records.
- You are uploading through Lightning, Flow, Lightning Web Components, Data Loader, or current Salesforce APIs.
Choose a video integration when:
- Customers need to record an issue without becoming Salesforce users.
- Agents need to request a video from the Salesforce Case workflow.
- Playback, captions, summaries, security, and video retention are important.
- You want to add visual context without treating every recording as a generic file upload.
Video capture is one component of a broader support technology stack. See our comparison of Salesforce customer support software for tools covering visual issue capture, telephony, knowledge management, automation, document generation, and reporting.
11. Frequently asked questions
Is the Salesforce Attachment object deprecated?
The Attachment object still exists for legacy data and integrations. However, Salesforce recommends using modern Notes and Salesforce Files experiences rather than designing new solutions around legacy Notes & Attachments.
Where is an Attachment stored in Salesforce?
The Attachment record stores its metadata and binary content in the Body field. ParentId identifies the Salesforce record to which the file is attached.
What is the difference between ContentDocument and ContentVersion?
ContentDocument represents the logical file.
ContentVersion represents a specific version of that file and contains version-specific information, including the uploaded binary data.
What is ContentDocumentLink?
ContentDocumentLink connects a Salesforce File to a record, user, group, or library.
It is the object commonly queried to find Salesforce Files related to a Case.
Why does my Attachment query not return files uploaded in Lightning?
Salesforce Files and legacy Attachments use different objects.
Query ContentDocumentLink and the related Files objects to retrieve modern file uploads.
Can I attach a video to a Salesforce Case?
Yes. You can upload a video as a Salesforce File or associate an externally hosted recording with the Case.
For a recurring customer-support workflow, Videolink can add video context and a customer video-request action to Salesforce records.
Sources and further reading
Salesforce, Understanding Salesforce Files
Salesforce, Changes to Notes and Attachments
Salesforce Developers, Attachment Field Reference
Salesforce Developers, ContentDocumentLink Object Reference
Salesforce Developers, Upload Files with Data Loader
