SharePoint

Required Scopes

To configure a Sync for SharePoint, you need to request the following scopes from your Microsoft OAuth application:

• Sites.Read.All
• Files.Read.All
• User.Read.All
• User.Read
• Group.Read.All
• offline_access

Learn more about configuring scopes for your app in Adding Integrations.

If you are using Permissions API, SharePoint requires these scopes to be configured as Application Permissions (not Delegated Permissions) in your Azure AD app registration. This requires certificate-based authentication and admin consent.

Follow the SharePoint: Using Application Permissions setup guide before enabling a sync.

Synced Objects

SharePoint supports the following Synced Objects:

• Files
• Permissions

Files

Send a request to Enable Sync to start a file sync.

Syncs for SharePoint can be created with one of the following configurations:

• Site Sync: All files in the specified SharePoint site will be synced.
• Folder Sync: Only files in the specified folder will be synced (recursively including all subfolders by default).
• Sync of specific files: Only a group of specific files will be synced.

Site Sync

Example

{
    "integration": "sharepoint",
    "pipeline": "files",
    "configuration": {
        "siteId": "contoso.sharepoint.com,12345678-1234-1234-1234-123456789012,87654321-4321-4321-4321-210987654321"
    }
}

siteId · string · required

The SharePoint Site ID to sync files from. This is required and specifies which SharePoint site’s document libraries should be synced.

mimeTypes · string[]

An optional array of MIME types to filter synced files. Only files matching the specified MIME types will be synced.

includeMetadata · boolean

Set to true to include each file’s SharePoint list item fields (custom columns and library metadata) on the synced File under customFields.metadata. Defaults to false. See File metadata for details.

Folder Sync

Example

{
    "integration": "sharepoint",
    "pipeline": "files",
    "configuration": {
        "folderId": "01ABCDEF2345GHIJKL/XYZ1234567890!123"
    }
}

Configuration options:

folderId · string · required

The SharePoint Folder ID to sync files from.

siteId · string

The SharePoint Site ID that this folder belongs to. If not specified, the Sync will use the site that the user selected when connecting their SharePoint account.

Warning: If the folder does not belong to the site specified, the Sync will fail.

shallowSync · boolean

Set to true to sync only the direct children of the specified folder, without recursing into subfolders. Defaults to false.

mimeTypes · string[]

An optional array of MIME types to filter synced files. Only files matching the specified MIME types will be synced.

includeMetadata · boolean

Set to true to include each file’s SharePoint list item fields (custom columns and library metadata) on the synced File under customFields.metadata. Defaults to false. See File metadata for details.

Sync of specific files

Example

{
    "integration": "sharepoint",
    "pipeline": "files",
    "configuration": {
        "fileIds": ["01ABCDEF2345GHIJKL/XYZ1234567890!456"]
    }
}

Configuration options:

fileIds · string[] · required

A list of SharePoint File IDs to limit the Sync scope to.

mimeTypes · string[]

An optional array of MIME types to filter synced files. Only files matching the specified MIME types will be synced.

includeMetadata · boolean

Set to true to include each file’s SharePoint list item fields (custom columns and library metadata) on the synced File under customFields.metadata. Defaults to false. See File metadata for details.

File metadata

Synced SharePoint files include additional metadata in the File customFields object:

• fullPath (always included): The file’s full path within its drive, built from the parent folder path and file name (for example, /drives/<driveId>/root:/Shared Documents/Reports/Q1.pdf). Use this when you need to display or reason about the location of a file in SharePoint without traversing the folder hierarchy yourself.
• metadata (included when includeMetadata is true): A flat object of the file’s SharePoint list item fields, including built-in columns and any custom columns defined on the document library. This is fetched per file using the Microsoft Graph listItem endpoint, so enabling it adds an extra API call per synced file.

Example synced file with includeMetadata enabled:

{
  "id": "...",
  "externalId": "01ABCDEF2345GHIJKL/XYZ1234567890!123",
  "name": "Q1-Report.pdf",
  "mimeType": "application/pdf",
  "customFields": {
    "fullPath": "/drives/b!.../root:/Shared Documents/Reports/Q1-Report.pdf",
    "metadata": {
      "Title": "Q1 Financial Report",
      "Department": "Finance",
      "ReviewStatus": "Approved",
      "Modified": "2024-04-01T10:00:00Z"
    }
  }
}

If a file does not have an associated list item (for example, items in a personal OneDrive context), the metadata field is omitted for that file.

Choosing Files and Folders

You can allow your user to select files from their SharePoint account in your app with the SharePoint File Picker provided by the Paragon SDK.

Showing the File Picker

Use the Paragon SDK in your frontend application to show the File Picker in your app.

The SDK provides an ExternalFilePicker class to load SharePoint’s JavaScript into your page and authenticate with your user’s connected SharePoint account.

let picker = new paragon.ExternalFilePicker("sharepoint", {
    onFileSelect: (files) => {
        // Handle file selection
    }
});

// Loads external dependencies and user's access token
await picker.init();

// Open the File Picker
picker.open();

You can configure the File Picker to listen for additional callbacks or to restrict allowed file types. Learn more about configuring File Picker options in the SDK Reference.