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

# Create a Sub-Org

> Create a sub-org with a unique name. Requires the ADMIN or OWNER role.

**POST** `/api/external/sub_orgs/`

Create a managed end-user SubOrg in the authenticated organization. Creation requires organization-wide access as described above.

## Request body

<ParamField body="name" type="string" required>
  Non-empty SubOrg name. The name must be unique within the organization.
</ParamField>

## Response

Returns the new [SubOrg](/sub-orgs/overview#suborg).

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

<ResponseField name="orgId" type="string">
  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`. Sub-orgs created through the API are `MANAGED`.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Creation timestamp (ISO 8601).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Last update timestamp (ISO 8601).
</ResponseField>

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

<ResponseField name="version" type="number">
  Record version number.
</ResponseField>

<RequestExample dropdown>
  ```json Request body theme={null}
  {
    "name": "PrimeVault customer"
  }
  ```

  ```bash cURL theme={null}
  # Sample only. Generate a new signed token for each request
  # (see Authentication). Tokens expire after 120 seconds.
  curl --request POST \
    --url "https://api.primevault.com/api/external/sub_orgs/" \
    --header "Authorization: Bearer <signed JWT>" \
    --header "Api-Key: <API key>" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "PrimeVault customer"
    }'
  ```

  ```typescript JavaScript SDK theme={null}
  const subOrg = await apiClient.createSubOrg({
    name: "PrimeVault customer",
  });
  console.log(subOrg.id, subOrg.controlMode);
  ```

  ```python Python SDK theme={null}
  from primevault_python_sdk.types import CreateSubOrgRequest

  sub_org = api_client.create_sub_org(
      CreateSubOrgRequest(name="PrimeVault customer")
  )
  print(sub_org.id, sub_org.controlMode)
  ```
</RequestExample>

<ResponseExample dropdown>
  ```json Response example theme={null}
  {
    "id": "a648fa0d-4ca9-4f4f-a520-7ef5e9db34eb",
    "orgId": "a30d5e99-7076-45da-a933-0d5642619340",
    "name": "PrimeVault customer",
    "controlMode": "MANAGED",
    "createdAt": "2026-09-14T12:00:00Z",
    "updatedAt": "2026-09-14T12:00:00Z",
    "isDeleted": false,
    "version": 1
  }
  ```

  ```typescript JavaScript SDK theme={null}
  interface SubOrg {
    id: string;
    orgId: string;
    name: string;
    controlMode: SubOrgControlMode | null;
    createdAt: string;
    updatedAt: string;
    isDeleted: boolean;
    version: number;
  }
  ```
</ResponseExample>


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