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

# Sub-Orgs

> Sub-accounts inside your organization. Use them to onboard your customers or keep business units separate.

A **sub-org** is a sub-account inside your PrimeVault organization. It follows the same model as a bank's master account with sub-accounts: your organization is the master, and each sub-org holds its own vaults, contacts, bank accounts, and transactions, separate from every other sub-org.

```mermaid theme={null}
flowchart TD
  Org["Your organization"] --> A["Sub-org: Customer A"]
  Org --> B["Sub-org: Customer B"]
  A --> A1["Vaults, contacts, bank accounts, transactions"]
  B --> B1["Vaults, contacts, bank accounts, transactions"]
```

## When to use a sub-org

* **Onboard your customers.** Create one sub-org per customer so each customer's funds, counterparties, and activity stay separate.
* **Separate business units or entities.** Give each legal entity, region, or product line its own sub-org.
* **Scope access.** Manage who can see and act on each sub-org separately, while you keep one view across the whole organization.

## How it works

1. [Create a sub-org](/sub-orgs/create-sub-org) with a name that is unique in your organization.
2. Pass its `id` as `subOrgId` when you create [vaults](/vaults/create-vault), [contacts](/blockchain-contacts/create-contact), and [bank accounts](/bank-accounts/create-bank-account), and when you get quotes or create transactions.
3. [List sub-orgs](/sub-orgs/list-sub-orgs) to find their IDs later.

<Note>
  Only API users with the `ADMIN` or `OWNER` role and organization-wide access can create sub-orgs. Your organization comes from authentication, so you can't act on another organization's sub-orgs.
</Note>

## Limits

* The API can create and list sub-orgs. It can't retrieve a single sub-org by ID, update one, or delete one.
* Sub-orgs created through the API are `MANAGED`.

<CardGroup cols={2}>
  <Card title="Create a Sub-Org" icon="plus" href="/sub-orgs/create-sub-org">
    **POST** `/api/external/sub_orgs/`
  </Card>

  <Card title="List Sub-Orgs" icon="list" href="/sub-orgs/list-sub-orgs">
    **GET** `/api/external/sub_orgs/`
  </Card>
</CardGroup>

## Data models

### SubOrg

<ResponseField name="id" type="string (UUID)">
  Sub-org ID. Pass it as `subOrgId` on other resources.
</ResponseField>

<ResponseField name="orgId" type="string (UUID)">
  Parent organization.
</ResponseField>

<ResponseField name="name" type="string">
  Sub-org name. Unique within the organization.
</ResponseField>

<ResponseField name="controlMode" type="SubOrgControlMode | null">
  `MANAGED` or `INDEPENDENT`. Some existing sub-orgs return `null`. Read-only. Sub-orgs created through the API are `MANAGED`.
</ResponseField>

<ResponseField name="createdAt" type="string (date-time)">
  Creation timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string (date-time)">
  Last update timestamp.
</ResponseField>

<ResponseField name="isDeleted" type="boolean">
  Deletion flag. Listed sub-orgs are not deleted.
</ResponseField>

### CreateSubOrgRequest

One required field: `name: string`.

### SubOrgListResponse

A paginated list: `results: SubOrg[]`, `nextCursor: string | null`, and `hasNext: boolean`.

## SDK methods

| Operation | JavaScript | Python | Returns |
| - | - | - | - |
| Create | `createSubOrg` | `create_sub_org` | `SubOrg` |
| List | `getSubOrgs` | `get_sub_orgs` | `SubOrgListResponse` |

## Errors

| Status | When it occurs |
| - | - |
| 400 Bad Request | Missing or invalid name, duplicate name, any supplied `controlMode`, unsupported `MAIN` creation, or an invalid pagination cursor. |
| 401 Unauthorized | Missing or invalid authentication, or an inactive API user. |
| 403 Forbidden | A role other than `ADMIN` or `OWNER`, an unavailable or inactive assigned home, or creation without organization-wide access. |


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