---
title: "Create smart group"
method: POST
path: "/users/v1/smart-groups"
tags: ["Users:v1:Smart Groups"]
---

# Create smart group

`POST /users/v1/smart-groups`

Create a new smart group under a specified segment. The smart group settings are currently based only on dropdown custom field type (support for additional field types will be added in the future). The created group is dynamic, meaning any new or existing users who meet the selected value criteria will be automatically added to the smart group.

## Request body

- SmartGroupCreateRequest
  - `name` string, required — The name of the smart group
  - `description` string — Description of the smart group
  - `groupSegmentId` integer, required — The ID of the group segment this smart group belongs to
  - `filters` SmartGroupFilters, required
    - `operator` 'and' | 'or' — An enumeration.
    - `dropdownFilters` DropdownFilter[] — Dropdown custom field filters
      - `fieldId` integer, required — The ID of the custom field to filter by
      - `optionIds` integer[], required — List of dropdown option IDs to match

## Response `200`

Successful Response

- APIResponseSmartGroupCreateResponse
  - `requestId` string
  - `data` SmartGroupCreateResponse, required
    - `id` integer, required — The unique identifier of the smart group
    - `name` string, required — The name of the smart group
    - `description` string — The description of the smart group
    - `groupSegmentId` integer, required — The ID of the group segment this smart group belongs to
    - `numberOfUsers` integer, required — The total number of users in the group (excluding admins)
    - `isAutomaticallyCreated` boolean — Whether this smart group is automatically created and system-managed: generated from a dropdown custom field that has its 'create a group per option' setting turned on. Automatically created groups cannot be edited or deleted directly — their name and membership are owned by the field and its options. Change them by editing the source custom field instead.
    - `adminUserIds` integer[] — User IDs of admins who can administer this group — every active owner plus every manager with an explicit per-cohort authorization. Populated only when the request includes the internal include_admin_user_ids flag; otherwise null.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/connecteam/apis/connecteam-api-documentation.md) · [All operations](https://skmtc.net/connecteam/apis/connecteam-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/connecteam/connecteam-api-documentation/versions/d8f7f302222e/schema)