---
title: "Create group"
method: POST
path: "/groups"
tags: ["Groups"]
---

# Create group

`POST /groups`

## Request

- Base URL: `https://demodesk.com/api/v2`
- URL: `https://demodesk.com/api/v2/groups`
- Auth: HTTP bearer

Creates a group of the company. Requires a company admin.

`visibility` defaults to `restricted` and `recordingAccess` to `own_group`. A `shared` group contains
every user of the company from the start and does not take recording access settings.
With `recordingAccess` set to `selected_groups`, `recordingAccessGroupIds` lists the other restricted
groups whose recordings the members can see. The group itself is always included and does not need
to be listed.

Group names are unique within the company, ignoring case and surrounding whitespace. The request
is not idempotent: repeating it returns `409` with the code `group_name_taken`. A script that did
not see the response can look the group up with `GET /groups?search=<name>` and compare the name.

Requests are checked in this order, and the first problem is reported:
`403 forbidden` for keys that are not company admins, `400` for malformed or inconsistent fields,
`409` for a name that is taken. Error codes: `unknown_field`, `invalid_name`, `invalid_visibility`,
`invalid_recording_access`, `invalid_recording_access_group_ids`, `recording_access_not_applicable`,
`recording_access_group_ids_not_applicable`, `recording_access_group_ids_required`,
`validation_failed`.

Rate limits:
- Global: 120 requests per minute per API key.
- Endpoint-specific: 30 requests per minute per API key, shared with `PATCH /groups/{groupId}` and
  `DELETE /groups/{groupId}`.

## Request body

- GroupCreateRequest
  - `name` string, required: Name of the group, without surrounding whitespace. Must be unique within the company, ignoring case.
  - `visibility` 'restricted' | 'shared': `restricted` groups have explicit members. `shared` groups contain every user of the company and cannot be combined with `recordingAccess` or `recordingAccessGroupIds`.
  - `recordingAccess` 'own_group' | 'selected_groups' | 'all_groups': Whose recordings the members can see in addition to the group's own. Only for restricted groups.
  - `recordingAccessGroupIds` string[]: Required and non-empty when `recordingAccess` is `selected_groups`, not allowed otherwise. Each id must belong to a restricted group of the company other than the default group.

## Response `201`

Group created.

- GroupResponse
  - `data` Group, required
    - `id` string, required: Internal group id.
    - `name` string, required: Name of the group.
    - `visibility` 'restricted' | 'shared', required: Visibility of the group. Shared groups contain every user of the company and their membership cannot be changed.
    - `default` boolean, required: Whether this is the default General group of the company. The default group cannot be changed through the API.
    - `recordingAccess` 'own_group' | 'selected_groups' | 'all_groups', nullable, required: Whose recordings the members of the group can see in addition to the recordings of the group itself. `own_group` adds nothing, `selected_groups` adds the groups listed in `recordingAccessGroupIds`, `all_groups` adds every restricted group of the company. `null` for shared groups, where the setting does not apply.
    - `recordingAccessGroupIds` string[], required: Ids of the groups whose recordings the members can see in addition to the group's own. Only filled when `recordingAccess` is `selected_groups`. The group itself is implicit and never listed.
    - `createdAt` string, date-time, required: When the group was created.
    - `updatedAt` string, date-time, required: When the group was last changed.

## Other responses

- `400`: Request validation failed.
- `401`: API key is missing or invalid.
- `403`: The authenticated user is not allowed to access this resource, e.g. it is not assigned to a company.
- `409`: The request conflicts with the current state of a resource, e.g. the group name is already taken.
- `429`: Rate limit exceeded.

## Changes

- **2026-10-18** `14d6c8e2e11a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/demodesk/apis/demodesk-public-api/changes/groups/post.md)

---

[API](https://skmtc.dev/demodesk/apis/demodesk-public-api.md) - [All operations](https://skmtc.dev/demodesk/apis/demodesk-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/demodesk/apis/demodesk-public-api/revisions/8729e4025dc9?raw)