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	`user_groups:write`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`name`	`Text`	The name of the group.

Conditional arguments

You must provide either team_id or both owner_email and members.

Name	Type	Description
`team_id`	`Text`	ID of an existing DX team to base the group on. When provided, the group will be created with the team’s members and the first team member as owner.
`owner_email`	`Text`	Email address of the group owner. Required when not using `team_id`.
`members`	`Array<Text>`	Array of email addresses for group members. Required when not using `team_id`.

Example requests

Create from 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 '{
    "name": "Frontend Team",
    "team_id": "team_id"
  }'

Create with Owner and Members

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",
    "owner_email": "owner_email",
    "members": ["user1@company.com", "user2@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_id": "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.
`validation_failed`	One or more supplied parameters did not pass validation.
`group_members_limit_exceeded`	Group members limit exceeded (max 100 members per group).