Attachment
An Attachment in Salesforce is the legacy mechanism for storing a file (PDF, image, document) directly tied to one parent record.
Definition
An Attachment in Salesforce is the legacy mechanism for storing a file (PDF, image, document) directly tied to one parent record. The Attachment object stores the binary content as a blob plus metadata (file name, content type, parent record ID) and renders inline on the parent's Lightning record page under a Notes & Attachments related list. Attachments preceded Salesforce Files (the modern file-storage feature based on ContentVersion and ContentDocument) and remain available for backward compatibility, though Salesforce strongly recommends Files for any new development.
Attachments are limited compared to Files. They cannot be shared with multiple records, lack version control, do not appear in Files Home or the Salesforce mobile experience, and count against per-org file storage on a different ledger than Files. New orgs still have the Attachment object available, but Lightning record pages by default surface Files rather than Attachments. Most production orgs have completed the Attachment-to-Files migration; remaining Attachments often sit on legacy custom objects whose page layouts never got updated. Reading any Salesforce documentation that uses Attachment as a primary file term should treat it as legacy and translate to Files for current implementations.
Attachment versus Files, and what to do with surviving Attachment data
The Attachment object schema
The Attachment standard object has ParentId (the record the file attaches to), Body (the binary content), Name, ContentType, BodyLength, and IsPrivate fields. One Attachment row equals one file attached to one parent record. Editing an Attachment replaces the file in place; there is no version history.
How Attachments differ from Files
Files use the ContentVersion object (for each version) plus ContentDocumentLink (to associate the file with parent records). Files support version history, multi-record association, sharing across users, and inclusion in Files Home. Attachments support none of these; they are simple, single-purpose, and out of step with modern Salesforce UX.
Why Salesforce moved to Files
The Attachment model worked when each record needed its own file. Modern use cases need shared files (one proposal PDF attached to a Lead and an Opportunity), versioned files (revised contract), and global file management. Files solve all three. Attachments were retained for backward compatibility but Salesforce stopped investing in them years ago.
Where Attachments still appear
Custom objects whose page layouts include the legacy Notes & Attachments related list still expose Attachment functionality. Email attachments processed through Email-to-Case can land in either Attachment or Files depending on the org's configuration. Older Apex code that creates Attachment records continues to work but should not be the pattern for new development.
Storage and licensing
Attachments count against File Storage in a Salesforce org. Files count against the same shared storage pool. Migrating Attachments to Files does not free additional storage; the files end up in the same bucket. The migration is about features and UX, not capacity.
Apex APIs and queries
Attachment is queryable through SOQL: SELECT Id, Name, ParentId FROM Attachment WHERE ParentId = '...'. Apex can create, read, update, and delete Attachment rows like any standard object. The Body field returns Blob; encoding to base64 is the standard path for transmitting via REST.
Migrating Attachments to Files
Salesforce provides documented patterns and partner tools for converting Attachments to Files in bulk. The process creates a new ContentVersion for each Attachment and a ContentDocumentLink to preserve the parent association. Custom Apex or third-party utilities handle thousands of conversions per batch.
Common pitfalls
Three patterns recur. Mixing Attachments and Files on the same object confuses users who do not know where to look. Custom Apex that depends on Attachment APIs is brittle; rewriting against ContentVersion is non-trivial but worth doing. Removing the Notes & Attachments related list from layouts is the gentlest deprecation path; aggressive deletion of legacy Attachment data can break old reports or integrations.
How to migrate from Attachments to Files
The migration is mostly mechanical conversion plus deliberate UI cleanup. The trick is doing both in step so users land on a consistent experience.
- Inventory remaining Attachment usage
Query Attachment by ParentId.Type to find which objects still carry Attachment data. Document the count per object.
- Build or buy a conversion utility
Use Salesforce-provided patterns or third-party tools to copy Attachment rows into ContentVersion + ContentDocumentLink records. Test thoroughly in sandbox.
- Run conversion in batches
Convert in chunks of thousands rather than millions. Verify each batch and reconcile counts before promoting to the next.
- Update page layouts
Remove Notes & Attachments related lists, add Files related lists. Confirm users see migrated files in the new surface.
- Decommission Attachment dependencies
After conversion verifies clean, retire any Apex code, Flows, or reports that query Attachment directly. Migrate them to ContentVersion.
- Attachments and Files share the same File Storage pool. Migration does not free storage; it just changes the file's representation.
- Custom Apex that queries Attachment will not return files migrated to ContentVersion. Update the code in the same release window as the data migration.
- Mixing the two surfaces on the same object confuses users. Remove Notes & Attachments after migration is verified.
- Email-to-Case can land attachments in either Attachment or Files depending on org settings. Confirm the configuration before assuming all new attachments are Files.
Trust & references
Cross-checked against the following references.
- Attachment API ReferenceSalesforce Developer Docs
- Salesforce Files OverviewSalesforce Help
Straight from the source - Salesforce's reference material on Attachment.
- ContentVersion API ReferenceSalesforce Developer Docs
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Discussion
Loading discussion…