# Tenants: Create a sub-tenant (https://docs.envocal.ai/api-reference/tenants/create-a-sub-tenant/)

> Creates a tenant under the tenant in the URL (current for the key's own tenant, or the id of one of its sub-tenants).

## POST `/v1/tenants/{tenantId}/sub-tenants`

Creates a tenant under the tenant in the URL (`current` for the key's own tenant, or the id of one of its
sub-tenants).

Allowed parent → child types: `main` → `main`, `sub`, `customer`; `sub` → `customer`. A `customer` tenant cannot
have children.

**Required permission:** `tenants:write`

### Parameters

| Name | In | | Type | Description |
| --- | --- | --- | --- | --- |
| `tenantId` | path | required | string | Tenant id, or `current` for the key's own tenant. Must be the key's tenant or one of its sub-tenants. |

### Request body

`application/json`: TenantCreateDto

| Field | Type | | Description |
| --- | --- | --- | --- |
| `name` | string | required | Display name. |
| `type` | `main` \| `sub` \| `customer` | required | Tenant type; must be allowed under the parent's type (see Tenant.type). |
| `domain` | string | nullable | Email domain of the organisation, unique across tenants. Optional. |
| `extraId` | string | nullable | Your own reference for this tenant. Optional. |
| `region` | `eu` | required | Data region the new tenant's data will live in. Required; usually the parent's region, but a global company may pick another. Cannot be changed afterwards. |

### Responses

**201** — TenantDto: Created. The `Location` header points to the new tenant.

| Field | Type | | Description |
| --- | --- | --- | --- |
| `id` | string | required | Tenant id. |
| `name` | string | required | Display name. |
| `parentId` | string | nullable | Parent tenant id. |
| `type` | `main` \| `sub` \| `customer` | required | Tenant type. Determines which child types it may contain: `main` → `main`, `sub`, `customer`; `sub` → `customer`; `customer` has no children. |
| `domain` | string | nullable | Email domain of the organisation (e.g. `example.com`), unique across tenants. Optional. |
| `extraId` | string | nullable | Your own reference for this tenant (e.g. a CRM or billing id). Optional, free text. |
| `region` | string | required | Data region the tenant's data lives in (`eu`); chosen when the tenant was created, and carried by its API keys (`evk_eu_...`). |

**400**: Invalid type or region, or the parent type cannot contain this type.

**401**: Missing, invalid, revoked or expired API key.

**403**: The key lacks the required permission, or the tenant/resource is outside its reach.

**429**: Rate limit exceeded. Retry after the number of seconds in the Retry-After header.

### Example

```bash
curl -X POST "https://api.envocal.ai/v1/tenants/current/sub-tenants" \
  -H "Authorization: Bearer evk_eu_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"string","type":"main","region":"eu"}'
```