Update User Group

This endpoint updates a user group’s name or description.

Endpoint

PUT /v1/user-groups/user-groups/:id

Authentication

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

Required Scope

user-groups:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	User group ID to update.

Request Body

Field	Type	Required	Description
name	string	No	New group name. Must not be empty and must be unique in your account. Leading and trailing spaces are removed.
description	string | null	No	New group description. Leading and trailing spaces are removed. null is stored as "".

Fields you leave out are not changed. Send a JSON body, at least {}. A request with no body returns 500.

Example Request Body

{
  "name": "Operations Leads",
  "description": "Users who coordinate operations work."
}

Example Request

cURL

curl -X PUT "https://api.crewsum.com/v1/user-groups/user-groups/36b735f8-4dd7-4c3c-836f-35d2fe84e872" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Operations Leads",
    "description": "Users who coordinate operations work."
  }'

JavaScript

const response = await fetch(
  "https://api.crewsum.com/v1/user-groups/user-groups/36b735f8-4dd7-4c3c-836f-35d2fe84e872",
  {
    method: "PUT",
    headers: {
      "x-api-key": process.env.CREWSUM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Operations Leads",
      description: "Users who coordinate operations work.",
    }),
  },
);
const result = await response.json();

HTTP

PUT /v1/user-groups/user-groups/36b735f8-4dd7-4c3c-836f-35d2fe84e872 HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>
Content-Type: application/json

{
  "name": "Operations Leads",
  "description": "Users who coordinate operations work."
}

Response

On success, the API returns HTTP 200 OK.

Example Response

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

Behavior

• This endpoint changes only the name and description. To replace the group’s members, use Set User Group Users.
• updatedAt is set on every successful request, even when no field changes.
• The response has the same shape as Get User Group.

Error Responses

Status	Meaning
400	"User group ID not found": the ID path segment was empty.
500	"Error updating user group": returned for every other failure, including an unknown group ID, an empty or duplicate name, and a missing body.

Authentication and scope failures are described in Errors.

Related Webhooks

This endpoint does not trigger a webhook.