userGroups.create

Creates a new user group. You can create a group either by specifying a DX team ID or by providing an owner and members explicitly.

Facts


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

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.

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`	Required. The name for the group.
`owner_email`	`Text`	Required. Email address of the group owner.
`members`	`Array<Text>`	Required. Array of email addresses.

With linked DX Teams

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

Custom group names are preserved when linked teams are renamed. If a group has one active linked team and shares that team’s name, it follows that team’s name changes.

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 owner will be automatically derived from that team. If multiple teams are specified, the group owner can still be explicitly specified.
`name`	`Text`	Optional. A nonblank name is used for the group, including when only one team is linked. Leading and trailing whitespace is trimmed. If omitted or blank, the first linked team’s name is used by default, including when multiple teams are linked.
`owner_email`	`Text`	Optional. Email address of the group owner. With a single DX Team, this field is ignored and derived from the team instead. If using multiple teams and owner is unspecified, the first team’s owner will be used by default.

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

Example requests

Create without linked DX Teams

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

Create with a single DX Team

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

Create with multiple DX Teams

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

Example response

This is a typical success response:

{
  "ok": true,
  "group": {
    "id": "group_id",
    "name": "Frontend Team",
    "owner_id": "owner_id",
    "owner_email": "owner@company.com",
    "team_ids": ["team_id"],
    "members": [
      {
        "id": "user_id",
        "email": "user@company.com",
        "name": "John Doe"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30: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.
`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).