> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useparagon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/getting-started/adding-an-integration#create-a-developer-app).

<Info>
  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](/resources/integrations/sharepoint#using-application-permissions) setup guide before enabling a sync.
</Info>

## Synced Objects

SharePoint supports the following Synced Objects:

* [Files](/managed-sync/api/file-schema)
* [Permissions](/managed-sync/permissions-api)

## Files

Send a request to [Enable Sync](/managed-sync/api/enable-a-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.

<Tabs>
  <Tab title="Site Sync">
    ```json Example theme={null}
    {
        "integration": "sharepoint",
        "pipeline": "files",
        "configuration": {
            "siteId": "contoso.sharepoint.com,12345678-1234-1234-1234-123456789012,87654321-4321-4321-4321-210987654321"
        }
    }
    ```

    <ParamField path="siteId" type="string" required>
      The SharePoint Site ID to sync files from. This is required and specifies which SharePoint site's document libraries should be synced.
    </ParamField>

    <ParamField path="mimeTypes" type="string[]">
      An optional array of MIME types to filter synced files. Only files matching the specified MIME types will be synced.
    </ParamField>

    <ParamField path="includeMetadata" type="boolean">
      Set to `true` to include each file's SharePoint list item fields (custom columns and library metadata) on the synced [File](/managed-sync/api/file-schema) under `customFields.metadata`. Defaults to `false`. See [File metadata](#file-metadata) for details.
    </ParamField>
  </Tab>

  <Tab title="Folder Sync">
    ```json Example theme={null}
    {
        "integration": "sharepoint",
        "pipeline": "files",
        "configuration": {
            "folderId": "01ABCDEF2345GHIJKL/XYZ1234567890!123"
        }
    }
    ```

    **Configuration options:**

    <ParamField path="folderId" type="string" required>
      The SharePoint Folder ID to sync files from.
    </ParamField>

    <ParamField path="siteId" type="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.
    </ParamField>

    <ParamField path="shallowSync" type="boolean">
      Set to `true` to sync only the direct children of the specified folder, without recursing into subfolders. Defaults to `false`.
    </ParamField>

    <ParamField path="mimeTypes" type="string[]">
      An optional array of MIME types to filter synced files. Only files matching the specified MIME types will be synced.
    </ParamField>

    <ParamField path="includeMetadata" type="boolean">
      Set to `true` to include each file's SharePoint list item fields (custom columns and library metadata) on the synced [File](/managed-sync/api/file-schema) under `customFields.metadata`. Defaults to `false`. See [File metadata](#file-metadata) for details.
    </ParamField>
  </Tab>

  <Tab title="Sync of specific files">
    ```json Example theme={null}
    {
        "integration": "sharepoint",
        "pipeline": "files",
        "configuration": {
            "fileIds": ["01ABCDEF2345GHIJKL/XYZ1234567890!456"]
        }
    }
    ```

    **Configuration options:**

    <ParamField path="fileIds" type="string[]" required>
      A list of SharePoint File IDs to limit the Sync scope to.
    </ParamField>

    <ParamField path="mimeTypes" type="string[]">
      An optional array of MIME types to filter synced files. Only files matching the specified MIME types will be synced.
    </ParamField>

    <ParamField path="includeMetadata" type="boolean">
      Set to `true` to include each file's SharePoint list item fields (custom columns and library metadata) on the synced [File](/managed-sync/api/file-schema) under `customFields.metadata`. Defaults to `false`. See [File metadata](#file-metadata) for details.
    </ParamField>
  </Tab>
</Tabs>

## File metadata

Synced SharePoint files include additional metadata in the [File](/managed-sync/api/file-schema) `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:

```json theme={null}
{
  "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"
    }
  }
}
```

<Info>
  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.
</Info>

## 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.

```javascript theme={null}
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](/apis/api-reference#externalfilepicker).