Overview

Data security is a top priority at Merge, and we know it is for you as well. This article explains what Common Model Scopes are, how they control which data Merge syncs from third-party systems, and how to configure them in your Dashboard or via API.

What are Common Model Scopes?

Common Model Scopes give you 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 third party — for example, disabling payroll or salary information

• Data objects you want to create in Merge — for example, enabling only the Employee and Employment Common Models

• Access levels (read and/or write) to the third-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.

You can:

• Include or exclude entire Common Models (e.g., disable the TimeOff model)

• Include or exclude specific fields within a model (e.g., disable salary fields in the 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, see the data filtering guide.

How do I 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

To adjust the Scopes for a model, first select Edit Scopes.

Disabling Scopes

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

Disabled Scopes mean that Merge returns null in API responses for the respective models and fields. However, depending on the integration's configuration, Merge 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, Merge 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 occurs. During this sync, Merge fetches 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 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 are automatically disabled after 90 days of inactivity — meaning no API requests have been made to the respective Common Model or field. For more information, see the Scopes minimization guide.

Linked Account Scopes

Default Scopes for an organization can be overridden per Linked Account in your Dashboard under each Linked Account, or via API.

New Linked Accounts 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's Scopes, the override persists until you select Reset to org default.

What Scope features are available on the Enterprise plan?

User Configurable Scopes

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

Scopes via API

You can configure Scopes programmatically using the Merge API before or after your customer links. For more information, see the API documentation.

• Before linking: POST /link-token

• After linking: POST /linked-account-scopes

Example: a POST /link-token request body that creates a link token 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 that updates a Linked Account's BankFeedTransaction 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"
    ]
  }
}

Who should I contact for help?

If you have questions or need help configuring Common Model Scopes, contact [email protected].