# Create a child project

Canonical page: https://docs.ovok.com/slim-apis/project/create-a-child-project

| Method | Path |
| --- | --- |
| `POST` | `/v1/slim/project/child` |

[Authentication](/authentication) · [Access policies](/access-policies)

Creates a child project under your current project and makes you its admin. Use it to set up a new customer or site below your organisation.

**Auth:** Bearer token for a project admin. No other role passes.
**Scope:** The new project becomes a direct child of the caller's project (from the token). A project that is itself a child may create children of its own.

## Request [#request]

### Body [#body]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | Project name. At least 1 character. |
| `id` | `string (uuid)` | No | Ignored. |
| `extension` | `any` | No | Ignored. |
| `address` | `object[]` | No | Postal addresses. Omit to have none. |
| `address[].use` | `"work"` \| `"temp"` \| `"old"` \| `"billing"` | No | Purpose of the address. |
| `address[].type` | `"postal"` \| `"physical"` \| `"both"` | No | Kind of address. |
| `address[].text` | `string` | No | The address as one text. |
| `address[].line` | `string[]` | No | Street lines. Each is a non-empty string. |
| `address[].city` | `string` | No | City. |
| `address[].district` | `string` | No | District. |
| `address[].state` | `string` | No | State. |
| `address[].postalCode` | `string` | No | Postal code. |
| `address[].country` | `string` | No | Country. |
| `contact` | `object[]` | No | Contact persons. Omit to have none. |
| `contact[].telecom` | `object[]` | No | Ways to reach the contact. |
| `contact[].telecom[].system` | `"email"` \| `"phone"` \| `"fax"` \| `"pager"` \| `"url"` \| `"sms"` \| `"other"` | No | Kind of contact point. |
| `contact[].telecom[].use` | `"work"` \| `"temp"` \| `"old"` \| `"mobile"` | No | Purpose of the contact point. |
| `contact[].telecom[].value` | `string` | No | The email address, phone number or URL. |
| `contact[].name` | `object` | No | The contact's name. |
| `contact[].name.use` | `"temp"` \| `"old"` \| `"official"` \| `"usual"` \| `"nickname"` \| `"anonymous"` \| `"maiden"` | No | Kind of name. |
| `contact[].name.prefix` | `string[]` | No | Name prefixes. |
| `contact[].name.given` | `string[]` | No | Given names. |
| `contact[].name.family` | `string` | No | Family name. |
| `contact[].name.suffix` | `string[]` | No | Name suffixes. |
| `contact[].address` | `object` | No | The contact's address, with the same fields as `address[]`. |
| `settings` | `object` | No | Project settings. |
| `settings.timeZone` | `string` | No | Time zone name, such as `Europe/Berlin`. Default `Europe/Berlin`. |
| `settings.trendsPeriod` | `object` | No | The daily window that trends cover. Omit to use the default. |
| `settings.trendsPeriod.start` | `string` | Yes, with `settings.trendsPeriod` | Start time as `HH:MM:SS`. |
| `settings.trendsPeriod.durationSeconds` | `number` | Yes, with `settings.trendsPeriod` | Length of the window in seconds. 0 or more. |

## Behaviour [#behaviour]

- Your project must already hold at least one access policy: the child gets a copy of every access policy of your project. Without one the request is refused with 424 and nothing is created.
- A second child with exactly the same `name` under the same parent is refused with 422.
- The whole create is all or nothing. A failure undoes what was written and answers the failure.
- On success Ovok:
  - creates the project with practitioner invitations and practitioner login enabled, and practitioner registration plus all patient registration, invitation and login disabled;
  - gives it its own Signals tenant and its own tenant code;
  - links it to your project;
  - copies your practitioner profile into it and adds you as an admin member;
  - seeds its thresholds from the global defaults.
- The organization stored inside the project is built from `name`, `address`, `contact` and `settings`. `settings.timeZone` defaults to `Europe/Berlin`. `id` and `extension` in the body are ignored.
- When the platform has it enabled, an Ovok support account is also added as a non-admin member holding the child's System Owner access policy. It is skipped when the child has no single policy of that name. This step never fails the create.
- Child project lists are refreshed right away.
- Returns `{ "projectId": "<new project id>", "success": true }`.


## Example [#example]

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/project/child' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example project",
    "contact": [{ "telecom": [{ "system": "email", "use": "work", "value": "team@example.com" }] }],
    "settings": { "timeZone": "Europe/Berlin" }
  }'
```


## Successful response [#successful-response]

`201` — The child project was created successfully.

```json
{ "projectId": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "success": true }
```

| Field | Type | Description |
| --- | --- | --- |
| `projectId` | `string (uuid)` | Id of the new child project. |
| `success` | `boolean` | Always `true`. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | The project or its Signals tenant could not be created. |
| [`401`](/errors/unauthenticated) | The bearer token is missing or invalid, or the session carries no project, user or profile. |
| [`403`](/errors/forbidden) | The caller is not a project admin. |
| [`409`](/errors/conflict) | Another create of the same name under the same parent is in progress. |
| [`422`](/errors/validation-failed) | The body fails validation, or your project already has a child project with this name. |
| [`424`](/errors/failed-dependency) | Your project has no access policy to copy into the child. Nothing was created; retry once it has one. |
| [`503`](/errors/service-unavailable) | The Signals tenant of the new project cannot be set up. Nothing was created. Retry shortly. |
