Business Units API

Overview

A Marketing Tenant is one customer account. Some customers are really several brands, dealerships, teams, or regions operating under one account — Business Units let a single Marketing Tenant be divided into flat, isolated data scopes, so each unit sees and edits only its own Pages, email templates, campaigns, forms, lists, and files, while the customer still administers everything as one account.

Every tenant already has a Default Business Unit that owns all pre-existing/unscoped data — adopting Business Units is incremental: a tenant "turns it on" simply by creating a second Business Unit. There is no global enablement flag and no migration required.

A user's Active Business Unit is the scope their requests act under. It travels as a signed, server-verified value — a caller cannot widen their own access by sending a different Business Unit id; the platform independently authorizes the Active Business Unit against the caller's actual membership and grants on every request.

Scope of this page

This page documents the two customer-facing, data-segregation endpoints. Tenant/Business-Unit lifecycle management (creating, renaming, or archiving a Business Unit; assigning memberships) is an operator/administration concern and is out of scope for this public API reference.

Core concepts

Term	Meaning
Marketing Tenant	The top-level customer account and primary data-isolation boundary.
Business Unit	A flat, subordinate data-access scope within one Marketing Tenant (e.g. one dealership or brand). Not a tenant, not an org.
Default Business Unit	The Business Unit present in every tenant. Owns legacy/unscoped data. Cannot be renamed or archived.
Active Business Unit	The Business Unit currently selected for a user's requests. Resolved and authorized server-side on every call.
Tenant Owner	A tenant membership whose reach extends to every active Business Unit, without holding an explicit grant for any one of them. Wire field: is_tenant_admin. It is a scope, not an administrative role.
Tenant Membership	An identity's explicit association with one Marketing Tenant. A membership can hold grants for multiple Business Units.
Business Unit Grant	The explicit association giving a Tenant Membership capabilities within one Business Unit.
Tenant-owned resource	A resource centrally governed by the tenant and readable by every Business Unit (e.g. approved templates, the Shared Asset Library, Core Slices), without transferring edit rights.
Business Unit–owned resource	A resource owned immutably by exactly one Business Unit (e.g. a campaign, a form, a Pages project). To make it available elsewhere, you create a copy in the other Business Unit — ownership itself never moves.

Authentication

All endpoints require API key authentication:

X-API-Key: your-api-key-here

List my Business Units

GET /api/client/v1/business-units

Returns the caller's own authorized, active Business Units — the set your requests may act under.

Example response

{
  "business_units": [
    { "bu_id": "default", "name": "Default", "slug": "default", "is_default": true },
    { "bu_id": "bu_sales_east", "name": "Sales — East", "slug": "sales-east", "is_default": false }
  ],
  "is_tenant_admin": false,
  "default_business_unit_id": "default"
}

is_tenant_admin: true means the caller is a Tenant Owner and reaches every active Business Unit, whether or not it appears in business_units.

List my tenant memberships

GET /api/client/v1/my-memberships

Returns the caller's own tenant memberships — useful when a single identity holds memberships in more than one Marketing Tenant and needs to choose which one to act under.

Example response

{
  "results": [
    {
      "tenant_id": "9f2e1c3a-1234-4a5b-8c9d-0e1f2a3b4c5d",
      "tenant_name": "Acme Co",
      "tenant_code": "acme-co",
      "is_tenant_admin": false,
      "status": "active"
    }
  ]
}

status is one of active, inactive.

How data segregation works

• Every Business Unit–owned resource carries an owning Business Unit; a missing/null value means it is Default-owned, so pre-existing data is unaffected by adopting Business Units.
• Reads return the union of: rows owned by your authorized Business Units, tenant-owned Shared rows, and Default-owned rows (when Default is authorized for you). An unauthorized caller sees nothing — the platform fails closed rather than leaving a query unconstrained.
• Ownership is immutable. There is no "move to a different Business Unit" operation for a resource — to make a copy available in another Business Unit, you create a new, independently-owned copy there (see Pages project duplication and the File Manager).
• Resource areas vary in how visibly they expose Business Unit scoping today: File Manager and Pages projects carry an explicit, immutable Business Unit field and enforce it server-side end to end; Campaigns, Forms, and email resources surface a business_unit column but are documented per-resource (see Marketing Campaigns and Forms).

Related

• File Manager API — Business Unit– and Shared-scoped asset storage.
• Pages & Documents API — Business Unit–owned Pages projects, and duplicating a project into another Business Unit.