Sub-entities (multi-tenant organizations)

When you need sub-entities

Your org has multiple semi-independent business units and you want each to have its own phone numbers, agents, and settings, all managed from one LumisReach seat. Common cases:

Healthcare network. One parent entity, many clinic locations, each with its own outbound numbers.
Franchise. One brand, many franchisees.
Agency. One agency, many end-client workspaces.

Every sub-entity is a Team with parent_organization_id pointing to your umbrella org. Members can belong to the umbrella, a specific sub-entity, or both. Phone numbers, calls, reputation tracking, and brand registration are all sub-entity-scoped.

Resource	Shared with umbrella	Owned by sub-entity
Caller Trust enterprise (LOA, EIN, DIR)	Yes. One umbrella LOA covers every sub-entity by default	Optional. A sub-entity can register its own enterprise if it has a separate legal identity
Phone numbers	✗	✓
Agents + voice config	✗	✓
Call history + recordings	✗	✓
Billing	Pooled at the umbrella org	n/a
HIPAA posture	Inherited on creation, editable per sub-entity	n/a

The reputation-enrollment service walks the hierarchy automatically: when a phone on a sub-entity is provisioned, it looks for a team-level enterprise first, then the parent org’s enterprise, then falls back to the Lumis Labs umbrella. So you register once at the umbrella, and every sub-entity’s numbers are covered.

API key scopes

Two scopes matter for sub-entities:

Org-scoped key — auth.teamId = umbrella org id. Sees every sub-entity under the umbrella. Use for HQ engineering or internal tools.
Sub-entity-scoped key — auth.teamId = sub-entity id. Sees only that sub-entity’s resources (phone numbers, calls, contacts). Use when issuing keys to per-location ops or to a vendor managing a single location.

A sub-entity-scoped key reading caller-trust endpoints (enterprise / brand / reputation) sees the parent umbrella’s registration — your one Branded Calling registration covers every child automatically. To issue sub-entity-scoped keys: as the umbrella admin, create them via the Settings → API Keys UI with teamId = subEntityId, or have a LumisReach admin issue one on your behalf from the carrier-registrations admin panel.

Endpoints

All sub-entity endpoints require:

An umbrella-org-scoped API key, OR
A user-scoped API key where the user is ADMIN / OWNER of exactly one organization.

Required scopes: sub_entities:read, sub_entities:write.

Create a sub-entity

curl -X POST https://api.lumisreach.com/v1/sub-entities \
  -H "Authorization: Bearer $UMBRELLA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northside Clinic",
    "slug": "northside-clinic"
  }'

{
  "data": {
    "id": 142,
    "name": "Northside Clinic",
    "slug": "northside-clinic",
    "parent_organization_id": 42,
    "hipaa_enabled": true,
    "member_count": 1,
    "phone_number_count": 0,
    "created_at": "2026-05-20T18:00:00.000Z"
  }
}

The new sub-entity inherits the parent’s HIPAA posture by default. The umbrella user who issued the request is auto-added as OWNER.

List sub-entities

curl https://api.lumisreach.com/v1/sub-entities?limit=50 \
  -H "Authorization: Bearer $UMBRELLA_KEY"

Paginated. Pass cursor=<id> from meta.cursor to fetch the next page.

Get one

curl https://api.lumisreach.com/v1/sub-entities/142 \
  -H "Authorization: Bearer $UMBRELLA_KEY"

Update

curl -X PATCH https://api.lumisreach.com/v1/sub-entities/142 \
  -H "Authorization: Bearer $UMBRELLA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northside Clinic — Pediatrics",
    "hipaa_enabled": true
  }'

Setting hipaa_enabled: true requires the umbrella org to have an executed BAA on file. If the flag won’t flip, email support@lumisreach.com.

Worked example: onboard a new location end-to-end

# 1. As the umbrella, create the sub-entity.
NORTHSIDE=$(curl -s -X POST https://api.lumisreach.com/v1/sub-entities \
  -H "Authorization: Bearer $UMBRELLA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Northside Clinic", "slug": "northside"}' | jq -r '.data.id')

# 2. Provision a number for that sub-entity.
#    (Until team_id is exposed on POST /v1/phone-numbers, use the
#    dashboard's sub-entity switcher and then read it back via the API.)
curl https://api.lumisreach.com/v1/phone-numbers?team_id=$NORTHSIDE \
  -H "Authorization: Bearer $UMBRELLA_KEY"

# 3. (Optional) Issue a sub-entity-scoped API key for the clinic's ops team
#    or vendor. They will see ONLY Northside's numbers, calls, and contacts.
#    Do this through the Settings → API keys UI with teamId=$NORTHSIDE
#    or via the admin carrier-registrations panel.

# 4. With the sub-entity-scoped key, the clinic can read the umbrella's
#    brand registration (inherited automatically — no separate Branded
#    Calling submission needed):
curl https://api.lumisreach.com/v1/caller-trust/brand \
  -H "Authorization: Bearer $NORTHSIDE_KEY"
# => returns the umbrella's brand DIR

Tenant isolation guarantees

A sub-entity-scoped key:

Reads: filters every resource (phone numbers, calls, contacts, messages, reputation) to teamId = subEntityId only. Never sees the umbrella’s or sibling sub-entities’ records.
Writes: created resources are tagged with teamId = subEntityId so they’re visible only within that sub-entity.
Caller-trust reads (enterprise, brand, reputation): walk up to the parent umbrella’s registration. Read-only — the sub-entity can see the brand it’s calling under, but cannot modify it. To edit, use an umbrella-scoped key.

If a sub-entity needs its own brand (separate legal entity, distinct CNAM), register it via POST /v1/caller-trust/enterprise using a key scoped to that sub-entity, then sign + submit via POST /v1/caller-trust/enterprise/sign-and-submit.

HIPAA inheritance

Creating a sub-entity under a HIPAA-enabled parent auto-inherits the flag. A sub-entity can opt out by setting hipaa_enabled: false, but that’s unusual — leave it on if the parent has an executed BAA. The parent’s BAA covers all sub-entities under it — no separate BAA per child. The hipaa_enabled flag on each sub-entity controls whether the runtime HIPAA gates apply to that specific child. See HIPAA & BAA coverage for what this flag gates and how to request a BAA.

Getting Started

Concepts

Phone Numbers

Caller IDs

Enterprise Registration

Enterprise Registration (Legacy)

Branded Calling

Calls

SMS

WebRTC

Documents

Reputation

Usage

Sub-entities (multi-tenant organizations)

When you need sub-entities

API key scopes

Endpoints

Create a sub-entity

List sub-entities

Get one

Update

Worked example: onboard a new location end-to-end

Tenant isolation guarantees

HIPAA inheritance

​When you need sub-entities

​What sub-entities share vs. own

​API key scopes

​Endpoints

​Create a sub-entity

​List sub-entities

​Get one

​Update

​Worked example: onboard a new location end-to-end

​Tenant isolation guarantees

​HIPAA inheritance

When you need sub-entities

What sub-entities share vs. own

API key scopes

Endpoints

Create a sub-entity

List sub-entities

Get one

Update

Worked example: onboard a new location end-to-end

Tenant isolation guarantees

HIPAA inheritance