userGroups.update

Updates an existing user group. You can update the name and/or the group members.

Any field that is omitted from the request is left unchanged.

Facts


Method	`POST https://api.getdx.com/userGroups.update`
Required scope	`userGroups:write`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`id`	`Text`	The group ID.

Without linked DX Teams

When a group is not linked to DX Teams, the group name, owner, and members must be set explicitly.

Name	Type	Description
`name`	`Text`	Optional. The name for the group. If omitted, remains unchanged.
`owner_email`	`Text`	Optional. Email address of the group owner. If omitted, remains unchanged.
`members`	`Array<Text>`	Optional. Array of email addresses to replace current group members. Group member updates replace the entire member list - to add a single member, include all existing members plus the new one. If omitted, remains unchanged.

With linked DX Teams

Groups can be linked to existing DX Teams to automate the management of group members and attributes.

Name	Type	Description
`team_ids`	`Array<Text>`	Required. Array of existing DX team IDs to base the group on. If only 1 team is specified, the group name and owner will be automatically derived from that team. If multiple teams are specified, group name and owner can still be explicitly specified. Pass an empty array to unlink the group from all DX Teams; the current name, owner, and members are retained until explicitly updated.
`name`	`Text`	Optional. The name for the group. With a single team, this field is ignored and derived from the team instead.
`owner_email`	`Text`	Optional. Email address of the group owner. With a single team, this field is ignored and derived from the team instead.

Note: when team_ids is present in the request, this behavior takes precedence over the “Without linked DX Teams” behavior.

Example requests

Update without linked DX Teams

curl -X POST https://api.getdx.com/userGroups.update \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -d '{
    "id": "group_id",
    "name": "Updated Frontend Team",
    "members": ["user1@company.com", "user3@company.com"],
    "owner_email": "owner@company.com"
  }'

Update with a single DX Team

curl -X POST https://api.getdx.com/userGroups.update \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -d '{
    "id": "group_id",
    "team_ids": ["team_id"]
  }'

Update with multiple DX Teams

curl -X POST https://api.getdx.com/userGroups.update \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -d '{
    "id": "group_id",
    "team_ids": ["team_id_1", "team_id_2"],
    "name": "Updated Frontend Team",
    "owner_email": "owner@company.com"
  }'

Transition group from linked to unlinked

curl -X POST https://api.getdx.com/userGroups.update \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -d '{
    "id": "group_id",
    "team_ids": [],
    "name": "Updated Frontend Team",
    "owner_email": "owner@company.com",
    "members": ["user1@company.com", "user3@company.com"]
  }'

Example response

This is a typical success response:

{
  "ok": true,
  "group": {
    "id": "group_id",
    "name": "Updated Frontend Team",
    "owner_id": "owner_id",
    "owner_email": "owner@company.com",
    "team_ids": ["team_id"],
    "members": [
      {
        "id": "user_id",
        "email": "user1@company.com",
        "name": "John Doe"
      },
      {
        "id": "user_id_2",
        "email": "user3@company.com",
        "name": "Jane Smith"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:45:00Z"
  }
}

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error	Description
`not_authed`	No authentication token provided.
`invalid_auth`	Some aspect of authentication cannot be validated.
`not_found`	Group with the specified ID not found.
`invalid_arguments`	One or more supplied parameters did not pass validation. Details are returned in `error_details`.
`group_members_limit_exceeded`	Group members limit exceeded (max 500 members per group).