Business Units Feature Guide

What is a business unit?

Business units are a powerful and flexible way to partition your data and control access to it. For example, a company with regional teams can give each team access to only the accounts in their region, without creating separate organizations.

Simply put, a business unit is both a group of users and API keys, and a tag applied to accounts. Non-account utility data entities derive their business unit associations from their related accounts.

Business units are a hierarchy

Business units form a tree structure. Your organization always has at least one business unit: the root business unit. The root business unit cannot be deleted, and does not have a parent. All other business units must have a single parent business unit, but business units can have any number of children. Consider the example below:

flowchart TD
    us["United States"] --- ny["New York"]
    us --- California
    ny --- Albany
    ny --- Rochester
    California --- la["Los Angeles"]
    California --- sf["San Francisco"]

United States is the root business unit. New York is a child of United States, and is a parent to Albany and Rochester.

For example, Albany is a descendant of United States, and United States is an ancestor of Albany, even though the two business units do not share a direct parent-child relationship.

Access flows down the tree.

A user assigned to New York has access to the data in New York, Albany, and Rochester, but that user cannot see data in United States.

Conversely, an account assigned to New York can be accessed by users assigned to New York or United States, but not users assigned to Albany or Rochester.

The generalization of this rule is:

• A user has access to all of the data in their assigned business units and all of the data in the descendants of those business units.
• An account can be accessed by users assigned to its business units or any of those business units' ancestors.

One result of this is that users assigned to the root business unit have full access to all the data in your organization.

This same system applies to API keys as well.

Access rules

Users, API keys, and accounts, are the only entities directly assigned to business units. See the entity relationship diagram below.

erDiagram
    direction LR
    Accounts }o--o{ Credentials : has
    Accounts }|--o{ Statements : has
    Accounts }o--o{ Meters : has
    Statements }o--o{ Meters : has
    
    Meters }o--o| Sites : "assigned to"
    Statements o|--|o File : "may have"
    "Business Units" }|--o{ Accounts : "assigned to"
    Users }o--o{ "Business Units" : "assigned to"
    "API Keys" }o--o{ "Business Units" : "assigned to"

An account always has at least one assigned business unit. If none are specified, the account is assigned to the root business unit for your organization.

A user or API key has access to a business unit if they are assigned to it or one of its ancestors in the business unit hierarchy.

The entity-specific access rules are as follows:

• Accounts
  • Accessible if the user has access to at least one of the account's business units
  • Accessible if the user created the account through a third party portal
  • Accessible if the user is assigned to the root business unit
• Credentials
  • Accessible if the user has access to at least one of the credential's accounts
  • Accessible if the user created the credential
  • Accessible if the user is assigned to the root business unit
• Meters
  • Accessible if the user has access to all of the meter's accounts
  • Accessible if the user created the meter through an intervals third party portal
  • Accessible if the user is assigned to the root business unit
• Sites
  • Accessible if the user has access to at least one of the site's meters
  • Accessible if the user created the site
  • Accessible if the user is assigned to the root business unit
• Statements (includes Discovered Statements)
  • Accessible if the user has access to all of the statement's accounts
  • Accessible if the user is assigned to the root business unit
• Files
  • Accessible if the user has access to the statement for the file
  • Accessible if the user created the file
  • Accessible if the user is assigned to the root business unit
• Other Users
  • Only accessible to users with the admin or business unit manager role
  • Accessible if the other user is assigned to a business unit the user has access to
• API Keys
  • Only accessible to users with the admin role
  • Accessible if the API key is assigned to a business unit the user has access to
  • Accessible if the user is assigned to the root business unit
• Webhooks
  • Accessible if created for a business unit the user has access to
  • See Webhook Changes

Entities that a user lacks access to are filtered out of the API results completely and will reject requests to retrieve them.

A few implications arise from these rules:

1. Users assigned to the root business unit have full visibility.
2. An entity is always visible to its creator, regardless of business unit assignments.
3. A user may have partial visibility for a credential's accounts or a site's meters, meaning some are visible and some are not.
4. For multi-account statements, a user must have access to all the accounts to view the statement. There is no partial visibility in these cases where the user can access only the parts of the statement related to accounts they have access to.
5. For accounts associated with multiple credentials, a user with access to the account always has access to ALL of its related credentials.

These rules are designed to prioritize security while minimizing impact on usability.

Examples

In the business unit hierarchy example from above, suppose you are assigned to only California and not New York, and there are two accounts:

• Account CA: assigned to California, so it is accessible to you
• Account NY: assigned to New York, so it is not accessible to you

The table below shows how the access rules play out for entities related to these accounts:

Seeing an entity's related business units

API resources for utility data entities now include lists of related business units. Each list element is an object containing the name and ID of the business unit.

For accounts, this is simply a new businessUnits array.

Since other entities derive their business units from the related accounts, there are two different lists:

1. The union, which is any business unit that at least one of the related accounts is assigned to
2. The intersection, which is the business units that all of the related accounts have in common

An empty intersection means no single business unit covers every related account, so the entity may not be visible to users assigned to only one of those business units.

The API resources for statements, meters, sites, and files therefore have both businessUnitsUnion and businessUnitsIntersection arrays.

The credential resource contains only businessUnitsUnion because credentials are accessible if a user has access to any one of their accounts, so all business units in the union have access.

In general, it is preferable for the union and intersection to be identical because a smaller intersection indicates that the related accounts are in different business units.

Example

Consider a statement with two accounts: Account CA, assigned to California, and Account NY, assigned to New York. Its business unit lists would be:

• businessUnitsUnion: California and New York, every business unit that any related account belongs to
• businessUnitsIntersection: empty, no single business unit is shared by every related account

If instead both accounts were assigned to California, the union and the intersection would both be just California.

Assigning business units

Assigning accounts

There are multiple ways to specify which business unit(s) an account should be assigned to.

• Accounts can be reassigned to a new business unit after creation using the existing update account endpoints.
  • https://docs.arcadia.com/reference/update-account
  • https://docs.arcadia.com/reference/set-account
• On credential, expected account, or file creation, the user may provide a list of business unit IDs to be assigned to the accounts created on the credential's first job.
  • For credentials, the requested business units will not apply automatically to accounts discovered under the same credential later.
  • If an account already exists and your organization is configured to disallow assigning multiple business units to a single account, the existing business unit assigned to the account is kept and the requested business unit from the credential is ignored.
  • If an account already exists and your organization is configured to allow assigning multiple business units to a single account, the requested business unit is added to the account's assigned business units.
• Each business unit has a distinct Connect URL. Submitting credentials through a business unit's Connect URL requests that business unit for the credential using the mechanism in the point above.
  • Business unit IDs may also be specified when generating an encoded Connect URL.

Assigning users and API keys

Admins may assign users and API keys to business units in Dashboard. API keys can also be managed via the API.

Redundant assignments

Accounts, users, and API keys cannot be assigned to both a business unit and one of its ancestors or descendants. For accounts, this is only relevant if your organization allows multiple business units per account.

For users and API keys, assigning a descendant business unit to a user or API key that already had the ancestor assigned would not change their access since the ancestor assignment already grants access to all its descendants.

For account, assigning an ancestor business unit to an account that already had the descendant assigned would not change its access since the descendant assignment already grants access to all its ancestors.

Consider the following scenario, which uses the same example hierarchy from earlier in the page.

flowchart TD
    us["United States"] --- ny["New York"]
    us --- California
    ny --- Albany
    ny --- Rochester
    California --- la["Los Angeles"]
    California --- sf["San Francisco"]

An account cannot be assigned to both Albany and New York because New York is an ancestor of Albany. It cannot be assigned to Albany and United States either for the same reason. However, it can be assigned to Albany and California, since Albany and California do not share an ancestor-descendant relationship. The same logic applies for users and API keys as well.

The rationale for this rule is that the redundant assignment would not have any functional impact on the access. Because access flows down the business unit hierarchy, New York already has access to all of the accounts assigned to Albany, so assigning New York to the accounts as well is unnecessary. Similarly, users assigned to New York already have access to Albany, so assigning Albany as well to such users would be unnecessary. Enforcing this rule minimizes the number of assigned business units and simplifies many operations.

Moving and deleting business units

Moving a business unit

You can change a business unit's parent to move it, along with all of its descendants, elsewhere in the hierarchy. A business unit cannot be moved underneath itself or one of its own descendants, since that would create a cycle.

Because access flows down the tree, moving a business unit changes which users and accounts can see one another. A move may also trigger ancestor auto-removal on affected accounts (see redundant assignments above): if the move would leave an account assigned to both a business unit and one of its new ancestors, the ancestor assignment is removed automatically.

Deleting a business unit

A few rules govern deletion:

• The root business unit cannot be deleted.
• A business unit that has children cannot be deleted. Move or delete its children first.
• When a business unit is deleted, its accounts are reassigned to a target business unit. You may specify the target; if you do not, the accounts move to the deleted business unit's parent.
• Users and API keys assigned to the deleted business unit simply lose that assignment; they are not moved to the target. A user or API key left with no assignments will lose data access, as described in the note under Access rules.

Deleting a business unit emits the BUSINESS_UNIT_DELETION webhook described under Webhook Changes.

Searching and filtering by business unit

There are two ways to narrow results by business unit on list and search endpoints: the businessUnitIds query parameter and search queries on business unit fields.

The businessUnitIds query parameter

The list endpoints for utility data entities all accept an optional businessUnitIds query parameter: a comma-separated list of business unit IDs that narrows results to those business units. Use this parameter when you want results scoped to specific business units.

GET /plug/accounts?businessUnitIds=bus_abc,bus_def

• Omitting the parameter returns results from all of the business units you have access to.
• You must have access to every business unit you specify. Requesting a business unit you do not have access to returns a 403.
• The parameter only narrows the results, never widens them.

Searching

You can also filter by business unit fields in search queries, the same way you filter by any other searchable field. The searchable fields depend on the entity:

Examples:

# Accounts in a specific business unit by ID
GET /plug/accounts?search=businessUnits.id=='bus_abc'

# Accounts in a business unit by name
GET /plug/accounts?search=businessUnits.name=='California'

# Statements where at least one related account is in a particular business unit by name
GET /plug/statements?search=businessUnitsUnion.name=='California'

# Cross-business-unit statements: no single business unit covers every related account
# Useful for finding entities that may be hidden from users assigned to only one business unit
GET /plug/statements?search=businessUnitsIntersection=isnull=

New roles

Managing business units is a powerful permission, so we have introduced a new role in between standard and admin to allow this ability to be granted more precisely. We have also added a read-only role.

In other words, for each action in the following table, the action can only be done within the business units the user has access to.

*If your organization is configured to allow viewing passwords

**Except for the Connect URL

Organization-level vs business unit-level configuration

This feature moves some configuration from the organization level down to the business unit level. The table below summarizes where each relevant setting lives.

Webhook Changes

Each business unit may have its own live webhook URL and sandbox webhook URL. Note: webhook parameters (query parameters and headers) are still configured at the organization level for now.

When an entity triggers a webhook, that webhook is sent to each of the entity's related business units (the union across related accounts) and all of those business units' ancestors, if those business units have the corresponding live or sandbox webhook URLs configured.

A distinct webhook ID is created for each URL and the sending is independent. The payloads are identical aside from the webhook ID.

The payload of each webhook now also includes a businessUnitIds array. This array contains the directly-related business units for the webhook. It does not include the ancestor business units that also receive the webhook.

The list and retrieve webhooks endpoints also enforce access rules: a user can only access webhooks for business units they have access to.

New webhooks

There are two new webhook types added for this feature:

See detailed examples on our webhooks page.

Changes for existing customers

Some properties have been moved from the organization level to the business unit level. For customers with Arcadia before July 29th, 2026, a root business unit has been created automatically for you based on your organization's existing configuration.

The name of the root business unit is the display name of your organization, and the webhook URLs of the root business unit are the webhook URLs for your organization. The Connect URL for your organization will continue to work, and data submitted via that URL will be assigned to your organization's root business unit.

All existing accounts, users, and API keys have been assigned to the root business unit.

Comparisons to other features