Set User Group Users

This endpoint replaces every member of a user group with the users you send.

Endpoint

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

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.

Request Body

Field	Type	Required	Description
userIds	string[]	Yes	The complete new member list. Every user must exist in your account. Send [] to remove every user. If it is missing, the API returns 500.

Example Request Body

{
  "userIds": ["user-a", "user-b"]
}

Example Request

cURL

curl -X PUT "https://api.crewsum.com/v1/user-groups/user-groups/36b735f8-4dd7-4c3c-836f-35d2fe84e872/users" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": ["user-a", "user-b"]
  }'

JavaScript

const response = await fetch(
  "https://api.crewsum.com/v1/user-groups/user-groups/36b735f8-4dd7-4c3c-836f-35d2fe84e872/users",
  {
    method: "PUT",
    headers: {
      "x-api-key": process.env.CREWSUM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      userIds: ["user-a", "user-b"],
    }),
  },
);
const result = await response.json();

HTTP

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

{
  "userIds": ["user-a", "user-b"]
}

Response

On success, the API returns HTTP 200 OK.

Example Response

{
  "message": "Successfully updated user group users",
  "data": {
    "id": "36b735f8-4dd7-4c3c-836f-35d2fe84e872",
    "name": "Operations",
    "description": "Users who manage operations work.",
    "userCount": 2,
    "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
      },
      {
        "userId": "user-b",
        "displayName": "Second User",
        "email": "second@example.com",
        "systemRole": "admin",
        "isArchived": false
      }
    ]
  }
}

Behavior

• This is a replace-all update. Crewsum removes every current membership, then adds the users you send. Both steps run together: if one fails, no membership changes.
• Duplicate IDs in userIds are added once. User IDs are not case-sensitive.
• Users you remove from the group lose the group’s project and task assignments. Those assignments are not copied to the users as direct assignments.
• Users you add receive the group’s project and task assignments.
• This endpoint does not change the group’s updatedAt value.
• 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 users": returned for every other failure, including an unknown group ID, user IDs that do not exist, and a missing userIds.

Authentication and scope failures are described in Errors.

Related Webhooks

This endpoint does not trigger a webhook.