Create User Group

This endpoint creates a named user group. You can add users to the group when you create it.

Endpoint

POST /v1/user-groups/user-groups

Authentication

Include your API key in the x-api-key header. See Authentication.

Required Scope

user-groups:write

Request Body

Field	Type	Required	Description
name	string	Yes	Group name. Must not be empty and must be unique in your account. Leading and trailing spaces are removed.
description	string | null	No	Group description. Leading and trailing spaces are removed. null or no value is stored as "".
userIds	string[]	No	Users to add to the group. Every user must exist in your account.

Example Request Body

{
  "name": "Operations",
  "description": "Users who manage operations work.",
  "userIds": ["user-a"]
}

Example Request

cURL

curl -X POST "https://api.crewsum.com/v1/user-groups/user-groups" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Operations",
    "description": "Users who manage operations work.",
    "userIds": ["user-a"]
  }'

JavaScript

const response = await fetch(
  "https://api.crewsum.com/v1/user-groups/user-groups",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.CREWSUM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Operations",
      description: "Users who manage operations work.",
      userIds: ["user-a"],
    }),
  },
);
const result = await response.json();

HTTP

POST /v1/user-groups/user-groups HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>
Content-Type: application/json

{
  "name": "Operations",
  "description": "Users who manage operations work.",
  "userIds": ["user-a"]
}

Response

On success, the API returns HTTP 201 Created.

Example Response

{
  "message": "Successfully created user group",
  "data": {
    "id": "36b735f8-4dd7-4c3c-836f-35d2fe84e872",
    "name": "Operations",
    "description": "Users who manage operations work.",
    "userCount": 1,
    "createdAt": "2026-05-27T18:00:00.000Z",
    "updatedAt": null,
    "assignments": [],
    "users": [
      {
        "userId": "user-a",
        "displayName": "User Display Name",
        "email": "placeholder@example.com",
        "systemRole": "assoc",
        "isArchived": false
      }
    ]
  }
}

Behavior

• Crewsum generates the group ID.
• Duplicate IDs in userIds are added once.
• users is sorted by displayName. userCount is the number of users in the group.
• assignments lists the group’s project and task assignments. A new group has none, so it is []. This API cannot add assignments to a group.
• Creating the group and adding its users are separate steps. If adding users fails, the group can exist without them.

Error Responses

Status	Meaning
500	"Error creating user group": returned for every failure, including an empty or duplicate name and user IDs that do not exist.

Authentication and scope failures are described in Errors.

Related Webhooks

This endpoint does not trigger a webhook.