# Create Child Organization

Create a new organization as a child of your company. It starts with no members: invite people with Create Invitation while sending the new id in X-Company-Id, which can seat its first Owner. The key's creator needs child_company:manage.

`POST https://connect.mindcloud.co/v2/child-companies`

Permissions: `child_company:manage`.

## Parameters

### Headers

- `X-Company-Id` (string): Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. Here a key acts in another organization only as one of its members: with "Use this key across all of your organizations" on, in an organization its creator belongs to with a role. Child organizations and MindCloud staff access do not reach this endpoint. Every response's X-Company-Id header names the organization it acted in. See [Organizations](https://mindcloud.co/docs/api/rest/introduction/organizations).

### Body

- `name` (string, required): The new organization name, up to 128 characters. Names are unique across MindCloud.
- `description` (string): A description, up to 2048 characters.

## Example request

```bash
curl --request POST \
  --url 'https://connect.mindcloud.co/v2/child-companies' \
  --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Acme West",
  "description": "West coast operations"
}'
```

## Response fields

- `id` (string): The child organization's id. Send it in X-Company-Id to call other endpoints on the child.
- `name` (string): The child organization's name.
- `description` (string): The child organization's description.
- `origin` (string): created when your company created it through the API, linked when an existing organization accepted your company as its parent in Cirra.
  Allowed values:
    - `created`
    - `linked`
- `linkedOn` (date): When the link started.
- `memberCount` (number): Members of the child organization, including pending invites.
- `ownerCount` (number): Active Owners. A child cannot be released while this is 0.

## Errors

- 403 Access denied (API_KEY_PERMISSION_DENIED, COMPANY_SCOPE_MISMATCH): `FORBIDDEN` / `API_KEY_PERMISSION_DENIED` "This API key needs the child_company:manage permission for this operation."
- 409 Not allowed (COMPANY_NAME_TAKEN, COMPANY_PARENT_PERSONAL_FORBIDDEN, COMPANY_PARENT_DEPTH_EXCEEDED, COMPANY_PARENT_CHILD_LIMIT_REACHED): `CONFLICT` / `COMPANY_PARENT_DEPTH_EXCEEDED` "A child organization cannot have children of its own."
- 429 Daily creation limit: `RATE_LIMITED` / `CHILD_COMPANY_CREATION_LIMIT_REACHED` "An organization can create at most 10 child organizations per day."
