Download Attachments from Salesforce: Complete Guide

Downloading files in Salesforce looks simple, but small details can cause issues. Errors, missing permissions, and wrong IDs waste time. Use this guide to avoid problems and pick the right method.

Identify the File Type (Attachment vs. File)

Confirm the type before you do anything. It determines how you query and download.

• Attachments (legacy): IDs start with 00P:

  

• Files (modern): Content model where 068  is ContentVersion and 069 is ContentDocument:

  

 

Why it matters: 

• Use the correct endpoint. 
• For “latest,” use ContentDocument.
• LatestPublishedVersionId (which gives you the 068 to download). 
• For a specific version, use that 068 directly. 
• 069 (ContentDocument) downloads resolve to the latest published version the user can access.

Check Permissions

Even with “View All Data”, access checks still apply.

• Attachments: access follows the parent record’s visibility.
• Files: access is controlled by ContentDocumentLink; Visibility and ShareType on CDL determine who sees the file on a record. If no CDL row exists, users can see the record but not the file.
• Watch for “File privacy on records = Private” – users may see the record but not the file. Set in File details; admins can expose the field ‘File Privacy on Records’ on the layout.
• “Query All Files” lets you query across the org (does not grant edit rights).

 Note: Granting CDL object permissions lets users manage file shares, but files only become visible when a corresponding CDL record exists and its Sharing/visibility settings allow it.

 

Validate Before You Download

Do not trust a checkbox like “Document Sent = True”. First confirm there’s actually a file attached to the record.

Quick UI check (recommended)

• Files (modern): Open the record → Related → Files. If the list is empty, there’s no ContentDocumentLink to this record (the file isn’t attached).
• Attachments (legacy): Open the record → Related → Notes & Attachments. If empty, nothing is attached. If you open an attachment, confirm the Parent Record points to the intended record.

  

  No attachment available under Notes & Attachments (Salesforce Opportunity example).

Optional automated checks (SOQL pre-checks):

• Files:

  SELECT ContentDocumentId
  FROM ContentDocumentLink
  WHERE LinkedEntityId = 'RECORD_ID' LIMIT 1 

• Attachments:

  SELECT Id 
  FROM Attachment 
  WHERE ParentId = 'RECORD_ID' LIMIT 1

 

Methods to Download Files and Attachments

Pick based on volume, control, and speed.

Manual download

Best for a few records: open the record, open the file, and download. Files can have multiple versions; confirm you are grabbing the correct one.

Data Export (weekly or on-demand)

Good for backups. Exports file binaries in bulk; expect post-processing. You cannot filter per record. In the ZIP, use the CSVs (with IDs like ContentDocumentId) to map payloads back to records.

Use this for backups or bulk downloads, not per record pulls, in Setup → Data Export you can schedule weekly or monthly or run Export Now, make sure to check include Files/Include Attachments. The result is one or more ZIP files with CSVs files.

Remember you can’t filter by record so after download you will need to map back each file using Attachment.csv and ParentId for Attachments, and for Files join ContentVersion.csv (ContentDocumentId) with ContentDocumentLink.csv (LinkedEntityId).

Direct URL patterns

Fast and scriptable when you already have IDs. Requires an authenticated session (or a public link). Attachment downloads use the FileDownload servlet with 00P… IDs. Files can be  downloaded via /sfc/servlet.shepherd/version/download/<ContentVersionId> (specific version) or /sfc/servlet.shepherd/document/download/<ContentDocumentId> (latest published).

Classic Documents (015…) also use the FileDownload servlet. These endpoints are not interchangeable.

The shepherd servlet can accept multiple ContentVersion IDs in one URL and return a ZIP (Files only; Attachments are not supported).

API approach (full control)

Stream the binary from the object’s blob field.

•  Attachment: Body (BLOB)
• File: ContentVersion.VersionData (BLOB)

In REST, blob endpoints return binary directly. In SOAP or some tools, you may receive Base64 and need to decode before saving.

Tip: Large or bulk exports often create duplicate names like “document.pdf”. Save with a pattern like RecordId-FileName or LinkedEntityId-VersionId-FileName to avoid collisions.

 

XL-Connector (user-friendly option)

Works with both Attachments and Files.

1) Connect XL-Connector to Salesforce.

2) Use Get Data (SOQL or Report) to pull Attachment or ContentVersion rows. For Files, prefer querying ContentDocumentLink and include ContentDocument.LatestPublishedVersionId:

3) Use Export Files and choose the destination folder:

4) (Optional) Include metadata columns (linked record, CreatedDate, OwnerId) for traceability.

5) Filter by date ranges or record IDs to keep the export focused.

6) Run the export and review the log for skips or permission issues.

You can find more information in our article: Mass-Downloading Documents from Salesforce.

 

After Download Best Practices

You can run these quick checks after export to confirm the export is complete and accessible:

• Open a sample file to confirm it is not corrupted.
• Rename files to avoid collisions (for example, RecordId-FileName).
• Store helpful metadata alongside files (linked record, dates, owner).
• Clean up org storage only after you verify the export and backups.

Common Pitfalls (Quick Checklist)

These are some quick checks you can do to avoid errors and empty downloads:

• Using an Attachment endpoint for a File (or the other way around).
• Assuming ParentId exists for Files (use ContentDocumentLink.LinkedEntityId).
• Forgetting File privacy settings (Private on Records).
• Grabbing the wrong version (download the intended ContentVersion ID).
• Using the wrong domain or host (internal vs. community).
• Skipping a pre-check; bulk jobs return empty outputs when nothing is linked.
• Expecting Data Export to filter per record (it cannot).

 

Conclusion

Identify the object (Attachment, File, or Classic Document), verify access via sharing or ContentDocumentLink, confirm something exists, then choose the right method: manual, Data Export, direct URL, API, or XL-Connector. Finish with post-download checks and clear naming so your files stay usable.