Introduction

Data security is a top priority at Merge, and we know it is for you as well! Scopes provide precise control over data, ensuring that only relevant Common Models and fields are synced by Merge. With Common Model scopes, you can control:

• Fields you want to sync from the 3rd party. For example - disable payroll, salary information

• Data objects you want to create in Merge. For example - enable only employee and employment common models

• Access levels (read and/or write) to the 3rd party systems.

You can set a default Common Model Scope for an entire category (HRIS, Ticketing, etc.) and optionally override it for individual linked accounts.

• Default Scopes apply to all new Linked Accounts within a given category.

• Linked Account Scopes apply only to a specific end user (Linked Account).

The Scopes applied to a Linked Account are determined first by the Linked Account Scopes, with Default Scopes serving as a fallback for any that haven’t been set.

Note: Common Model Scopes operate at the object type and field level, not the individual record level.

You CAN:

- Include/exclude entire common models (e.g., disable the Time Off model)

- Include/exclude specific fields within a model (e.g., disable salary fields in Employee model)

You CANNOT:

- Filter individual records (e.g., only employees in Sales department)

- Filter subsets of objects (e.g., only tickets created in the last year)

For record-level filtering, check the data filtering guide.

How to configure Common model Scopes?

Checking Scopes

You can check the Scopes tab in your Merge Dashboard to see the various access levels for each Common Model and field.

Adjusting Scopes

If you want to adjust the Scopes for a model, first switch the toggle on the top right from "Viewing" to "Editing".

Disabling Scopes

Fully disabling a Common Model Scope will also disable all its associated fields. You can also disable a specific Common Model field.

Disabled Scopes mean that Merge will return null in API responses for the respective models and fields. However, depending on the integration's configuration, we may still need to make requests to fetch that data. For example, if an integration returns data for multiple Common Models through a single endpoint, we will need to call that endpoint if another corresponding Common Model remains enabled.

Enabling Scopes

By default, Merge only syncs data that has changed since the last sync.

However, when you enable a new Scope, a full sync will occur. During this sync, Merge will fetch all items from your Linked Accounts, regardless of the date of the last change. This process ensures that previously disabled fields for all items are populated. Depending on the amount of data being synced and the rate limits set by our integration partners, this sync may take longer than a regular sync. You can continue to work with your account data while the sync is in progress, but the newly added data will not be available for all items until the sync is complete.

Auto-disabled Scopes

Common Models will be automatically disabled after 90 days of inactivity, meaning no API requests have been made to the respective Common Model or field. See the below guide for more information:

• 📄 Scopes minimization

Linked Account Scopes

Default scopes for an organization can be overridden per Linked Account in our Dashboard under each Linked Account or via API.

New Linked Accounts will follow the default Scopes set per category unless you explicitly override those preferences on a per Linked Account basis. Once you override a Linked Account Scopes it will be overridden unless you "reset to org default".

Enterprise plan features

User Configurable Scopes

To give your users control over their Scopes during the linking flow, simply mark the model or field as optional in the Dashboard. Models and fields marked as optional will be enabled by default but can be disabled by your users before connecting.

Scopes via API

You can configure scopes programmatically using our API before or after your customer links. For more information, please refer to our API documentation.

• Before linking: POST /link-token

• After linking: POST /linked-account-scopes

Example: A POST /link-token request body to create a link token with overriding the Group and Permissions File Storage scopes to be enabled

{
    "integration": "sharepoint",
    "end_user_origin_id": "123456",
    "end_user_email_address": "[email protected]",
    "end_user_organization_name": "name",
    "require_selective_sync": false,
    "linked_account_credentials": {
        "oauth_access_token": "oauth_token_here"
    },
    "category_common_model_scopes": {
        "filestorage": [
            {
                "model_name": "Permissions",
                "model_permissions": {
                    "READ": {
                        "is_enabled": true
                    }
                }
            },
            {
                "model_name": "Group",
                "model_permissions": {
                    "READ": {
                        "is_enabled": true
                    }
                }
            }
        ]
    }
}

Example: A POST /linked-account-scopes request body to update a Linked Account's Bank Feed Transaction model and field level scopes

{
  "model_name": "BankFeedTransaction",
  "model_permissions": {
    "READ": {
      "is_enabled": true
    },
    "WRITE": {
      "is_enabled": true
    }
  },
  "field_permissions": {
    "enabled_fields": [
      "amount",
      "created_at",
      "credit_or_debit",
      "description",
      "modified_at",
      "payee",
      "source_transaction_id",
      "transaction_date",
      "transaction_type"
    ],
    "disabled_fields": [
      "bank_feed_account"
    ]
  }
}