Move or Copy SharePoint Files: Browser, CSOM and API Choices

Use SharePoint's Move to or Copy to commands for occasional user-driven work. Use a supported asynchronous API for repeatable or high-volume operations. The older SP.MoveCopyUtil JavaScript pattern remains historical context, but it should not be the default architecture for a new SharePoint Online solution.

The difficult part is not moving bytes. It is preserving the document behaviour the business expects.

Choose the route first

Browser commands

Use Move to or Copy to when a user can select the source and destination and then inspect the result. This is the simplest route and keeps the operation inside SharePoint.

Permissions, destination policy, file locks, schema differences and service limits can still block the operation. Test with the actual libraries and content types involved.

Microsoft 365 Copy and Move API

For background jobs, Microsoft documents the Microsoft 365 Copy and Move API. It creates an asynchronous job and returns identifiers that a client can monitor.

The API exposes explicit options for move mode, version history, schema mismatch, name conflicts and locks. Those options are a warning that preservation is not automatic. For example, the documented default for IgnoreVersionHistory means version history is ignored unless your implementation requests the required behaviour.

Microsoft Graph

Microsoft Graph offers file operations for drive items. Its copy operation is asynchronous and returns a monitor URL. Check the operation's current parameters, permissions and limitations before choosing it for SharePoint content.

MoveCopyUtil

The CSOM class still exposes methods such as MoveFolderByPath and CopyFileByPath.

Use current CSOM packages and modern authentication. Do not copy a 2016 page-injected JavaScript sample into SharePoint Online and assume classic script-loading or authentication behaviour still applies.

Inventory what must survive

Before moving content, decide whether the destination must retain:

version history
created and modified dates
author and editor values
content type and all required columns
unique permissions and sharing links
retention labels or records state
document IDs
approval and checkout state
links from pages, workflows or external systems

A successful copy can still be a failed migration if any required item changes.

A safe operating sequence

Select a representative test set, including folders, large files, versioned files and custom content types.
Confirm source and destination permissions with a non-admin test user.
Align required columns and content types where the chosen method needs matching schemas.
Run a copy first when the business process permits it.
Monitor the asynchronous job rather than treating an accepted request as completion.
Compare counts, metadata, versions and permissions at the destination.
Open representative files and test dependent links or workflows.
Move or remove the source only after the acceptance checks pass.

For bulk work, make the operation restartable. Record each source URL, destination URL, job ID, result and error. A retry should not create uncontrolled duplicates.

Common failure boundaries

The destination is missing: the user or app may not have permission to see it.
A file is locked: decide whether to wait, fail or use a documented bypass option with an approved risk.
Metadata does not match: do not silently discard required fields.
The request was accepted but content is absent: asynchronous acceptance is not completion.
Links break after a move: test document IDs, sharing links and pages that referenced the old path.
Versions differ: verify the chosen API option and destination version settings.

What validation proves

Matching counts and sampled metadata prove only the items checked. For regulated or business-critical libraries, define a fuller reconciliation and approval process before deleting the source.

Sources

For more SharePoint file and governance patterns, join the SharePoint & Teams Admins Space.