> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumisreach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-entities (multi-tenant organizations)

> Provision and manage child workspaces — clinic locations, franchisees, end-client accounts — under one umbrella organization.

## 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.

## What sub-entities share vs. own

| 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

```bash theme={null} theme={null}
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"
  }'
```

```json theme={null} theme={null}
{
  "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

```bash theme={null} theme={null}
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

```bash theme={null} theme={null}
curl https://api.lumisreach.com/v1/sub-entities/142 \
  -H "Authorization: Bearer $UMBRELLA_KEY"
```

### Update

```bash theme={null} theme={null}
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

```bash theme={null} theme={null}
# 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](/concepts/hipaa) for what this flag gates and how to request a BAA.