Help Center

Understanding App Distribution

When configuring your app for the CRM Marketplace, you define how it is distributed and installed by choosing from several distribution model options. These settings determine who can discover, install, and use your app, as well as how access tokens are generated. This guide covers the available configuration fields and their implications.

Distribution Configuration Fields

You can configure your app's distribution using three primary fields:

Target User: Specifies whether the app is intended for use by an Agency or a Sub-account. Most apps target Sub-accounts, as this is the recommended and most common use case. This setting cannot be changed once your app is configured.
Who Can Install: Defines whether the app can be installed by Both Agency and Sub-account users or by the Agency Only. For maximum reach, it is recommended to allow both to install. Choose Agency Only if your app is a white-labeled feature meant only for agencies to deploy to their sub-accounts.
Bulk Installation: Indicates whether an agency can install the app to multiple sub-accounts in one operation. All new apps are set to Yes by default, and this setting cannot be reverted to No once enabled.

Private App Installation Limits

If your app is set as Private, it is subject to installation limits during its pilot phase. A Private app can be installed in up to 5 agencies. If a sixth agency attempts to install it, the installation will be blocked until you either publish the app as Public or pass a Security Review. Each agency counts as one install, regardless of how many sub-accounts the app is installed within, and counts are updated in real time when an app is fully uninstalled.

Distribution Scenarios and Token Handling

Depending on your distribution configuration, the installation process and token retrieval vary:

If the target user is an Agency, an agency user installing the app will receive an access token with userType: Company and isBulkInstallation: false.
If the target user is a Sub-account and both can install, a sub-account user installing will receive a token with userType: Location and isBulkInstallation: false. An agency user installing will also receive a userType: Location token if bulk installation is not enabled.
If bulk installation is enabled for a Sub-account target, an agency user performing a bulk install will receive a token with userType: Company and isBulkInstallation: true. To access sub-account data, you must use the agency token to retrieve location-specific tokens for each installed sub-account and listen for AppInstall webhook events to handle new installations automatically.

Backward Compatibility

For existing apps, certain legacy distribution types are mapped to the new configuration fields to maintain compatibility. If your app was previously configured as Agency Only, it will map to the Agency target user. If it was Sub-account Only, it maps to Sub-account target with installation allowed by both but bulk installation disabled. To maximize reach, you can update these settings—for example, enabling bulk installation or allowing sub-account admins to install—after implementing the necessary OAuth flows.

Target User: Agency

Choose this option if your app's functionality is relevant only at the agency level. The app will be listed exclusively in the agency marketplace, and only agency admins or owners can install or uninstall it. Payments are handled by the agency, and the app cannot be resold to sub-accounts.

Target User: Sub-account (Both Can Install)

Select this if your app is designed for sub-account use. It will be listed in both the agency and sub-account marketplaces. Both agency and sub-account admins can install it, and if bulk installation is enabled, agencies can deploy it to multiple sub-accounts at once.