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.

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.
`name`	`Text`	Optional. The name for the group. With a single team, this field is ignored and derived from the team instead. If using multiple teams and name is unspecified, the first team’s name will be used by default.
`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).