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

# Sub-entities

> Create and manage child workspaces, like stores, locations or an agency's dealers, under one parent workspace.

A sub-entity is a workspace whose parent is your workspace. Use one per store, clinic location, franchisee or
agency client. Each child keeps its own phone numbers, agents, contacts, calls and recordings. The parent
creates and lists them, and its caller registration covers them.

Agencies doing this from the app should read [Add a dealer workspace](https://docs.revdesk.com/partners/add-dealer-workspace.md).

## What a child shares and owns

| Resource | Owned by the child | Comes from the parent |
| - | - | - |
| Phone numbers, agents, contacts, calls | Yes | No |
| Branded calling registration (caller trust) | Optional | Yes, unless the child registers its own |
| HIPAA setting | Editable | Copied at creation, and can't be turned off while the parent has it on |

When RevDesk looks up a child's caller registration, it uses the child's own registration first, then the
parent's. Register once on the parent and every child's numbers are covered.

## Keys and scopes

The sub-entity endpoints need an API key created in the **parent** workspace, with these scopes:

* `sub_entities:read` to list and read children.
* `sub_entities:write` to create and rename them.
* `compliance:write` as well, to change `hipaa_enabled`. It's never granted by default.

A key created **inside a child** workspace (switch to it, then **Settings › API Keys**) sees only that child's
numbers, calls, contacts and messages, and what it creates belongs to that child. Give these to a location's
own team or a vendor who manages one location. A child key can read the parent's caller registration through
`/v1/caller-trust/*` but can't change it.

## Endpoints

### Create

```bash theme={null}
curl -X POST https://api.revdesk.com/v1/sub-entities \
  -H "Authorization: Bearer $PARENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ridgeline Motors", "slug": "ridgeline-motors" }'
```

```json theme={null}
{
  "data": {
    "id": "0193a1c2-7d4e-7b8a-9f10-2c3d4e5f6a7b",
    "name": "Ridgeline Motors",
    "slug": "ridgeline-motors",
    "parent_organization_id": "0192f0aa-1b2c-7d3e-8f40-5a6b7c8d9e0f",
    "hipaa_enabled": false,
    "member_count": 1,
    "phone_number_count": 0,
    "created_at": "2026-11-17T18:00:00.000Z"
  }
}
```

`slug` is optional. Without it, RevDesk makes one from the name. Slugs are lowercase letters, numbers and
hyphens, up to 64 characters, and unique across RevDesk; a taken slug returns `409`. The person who owns the
key becomes the child's owner.

### List

```bash theme={null}
curl "https://api.revdesk.com/v1/sub-entities?limit=50" \
  -H "Authorization: Bearer $PARENT_KEY"
```

Newest first, up to 100 per page. Pass `meta.cursor` back as `cursor` for the next page. `member_count` and
`phone_number_count` show which children are live.

### Get one

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

A child that isn't under your workspace returns `403`.

### Update

```bash theme={null}
curl -X PATCH https://api.revdesk.com/v1/sub-entities/$CHILD_ID \
  -H "Authorization: Bearer $PARENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ridgeline Motors - Service" }'
```

You can change `name` and `hipaa_enabled`.

## HIPAA

A child of a HIPAA-enabled parent starts HIPAA-enabled. While the parent has HIPAA on, setting
`hipaa_enabled: false` on a child returns `403`. Turning HIPAA on for a child also sets its call-recording
retention to 30 days, which you can change per number afterward. The parent's BAA covers its children. See
[HIPAA and BAA](https://docs.revdesk.com/trust/hipaa.md).

## Own caller registration

If a child is a separate legal business with its own caller name, register it with a key scoped to that
child: `POST /v1/caller-trust/enterprise`, then `POST /v1/caller-trust/enterprise/sign-and-submit`. See
[Caller trust](https://docs.revdesk.com/concepts/caller-trust.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.