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

# Create New Group

`POST /groups`

Creates a new group within your organization. Supply a name for the group. Optionally provide created_by_user_id (the VOMO user ID of the group owner, who must be a member of your organization), a parent_id to nest the group under an existing group, and a members array of user IDs to immediately add members upon creation.

## Request body

- GroupWriteRequest — Request body for creating or updating a group.
  - `name` string, required — The name of the group
  - `description` string, nullable — A description for the group
  - `member_moniker` string — A word describing a group member
  - `subgroup_moniker` string — A word describing subgroups
  - `created_by_user_id` integer — Optional. If provided, must be an existing user who is a member of the organization.
  - `parent_id` integer — The VOMO Group ID to set as the parent group of the newly created group
  - `members` integer[] — User IDs to set as the group's membership. On create (POST), these become the initial members. On update (PUT), this **replaces** the existing membership — any current member omitted from the array is removed from the group. Pass an empty array to clear all members.

## Response `200`

Returns the newly created group record. Note: on success this endpoint returns 200 OK, not 201 Created.

- object
  - `data` GroupResource — List of Groups
    - `id` integer — The ID of the group
    - `name` string — The name of the group
    - `description` string — A description for the group
    - `has_subgroups` boolean — If the group has subgroups
    - `parent_id` integer — The group ID of the parent group
    - `subgroups` GroupResource[] — Child subgroups of this group. Present only when the 'children' relation is loaded (e.g. on detail endpoints).
    - `parent` GroupResource — recursive
    - `created_at` string, date-time — The date and time the group was created at
    - `updated_at` string, date-time — The date and time the group was last updated at

## Other responses

- `401` — Authentication credentials are missing or invalid.
- `422` — One or more request fields failed validation. Check the errors map for details.
- `429` — You have exceeded the rate limit of 30 requests per minute per API key.
- `500` — An unexpected server error occurred.

---

[API](https://skmtc.dev/vomo/apis/vomo-api.md) · [All operations](https://skmtc.dev/vomo/apis/vomo-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vomo/vomo-api/revisions/1582d52b5f1f/schema)