---
updatedAt: 2026-01-27T16:14:54.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# Smart Groups

Smart Groups in Connecteam allow you to organize users dynamically based on custom field values. Users are automatically added or removed from groups based on their matching criteria.

## Available Endpoints

| Method | Endpoint                              | Description                    |
| :----- | :------------------------------------ | :----------------------------- |
| GET    | /users/v1/smart-groups                | List all smart groups          |
| POST   | /users/v1/smart-groups                | Create a new smart group       |
| PUT    | /users/v1/smart-groups/{smartGroupId} | Update an existing smart group |
| DELETE | /users/v1/smart-groups/{smartGroupId} | Delete a smart group           |
| GET    | /users/v1/smart-group-segments        | List all smart group segments  |
| POST   | /users/v1/smart-group-segments        | Create a new segment           |

***

## Get Smart Groups

`GET /users/v1/smart-groups`

### Query Parameters

| Parameter | Type    | Description                |
| :-------- | :------ | :------------------------- |
| id        | integer | Filter by smart group ID   |
| name      | string  | Filter by smart group name |

### Response Example

```json
{
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "data": {
    "smartGroups": [
      {
        "id": 123456,
        "name": "Sales Team",
        "description": "All users in sales department",
        "segmentId": 789,
        "usersCount": 25
      }
    ]
  }
}
```

***

## Create Smart Group

`POST /users/v1/smart-groups`

### Request Body

| Field          | Type    | Required | Description                                           |
| :------------- | :------ | :------- | :---------------------------------------------------- |
| name           | string  | Yes      | Unique name for the smart group                       |
| groupSegmentId | integer | Yes      | ID of the segment this group belongs to               |
| description    | string  | No       | Description of the smart group                        |
| filters        | array   | No       | Array of filter objects (dropdown custom fields only) |

### Filters Structure

Filters allow you to automatically include users based on dropdown custom field values:

```json
{
  "filters": [
    {
      "customFieldId": 123456,
      "optionIds": [1, 2, 3]
    }
  ]
}
```

> 📝 Note
>
> **Currently, only dropdown custom fields are supported for filters. Other field types cannot be used as filter criteria.**

### Request Example

```json
{
  "name": "Marketing Team",
  "groupSegmentId": 789,
  "description": "All users in marketing department",
  "filters": [
    {
      "customFieldId": 6208757,
      "optionIds": [1, 2]
    }
  ]
}
```

### Success Response (201)

```json
{
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "data": {
    "id": 123456,
    "name": "Marketing Team",
    "description": "All users in marketing department",
    "segmentId": 789
  }
}
```

### Error Responses

| Status | Error                     | Description                                      |
| :----- | :------------------------ | :----------------------------------------------- |
| 400    | Invalid segment           | The specified segment ID does not exist          |
| 400    | Invalid custom field      | Custom field ID not found or not a dropdown type |
| 400    | Invalid option ID         | Option ID does not exist for the custom field    |
| 409    | Group name already exists | A smart group with this name already exists      |

***

## Update Smart Group

`PUT /users/v1/smart-groups/{smartGroupId}`

### Request Body

Same structure as Create. Fields not specified will remain unchanged.

> 🚧 Important
>
> **Filter changes will override existing filters entirely. Include all desired filters in the update request.**

***

## Delete Smart Group

`DELETE /users/v1/smart-groups/{smartGroupId}`

### Success Response (200)

```json
{
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "data": {
    "success": true
  }
}
```

### Error Responses

| Status | Error                 | Description                                 |
| :----- | :-------------------- | :------------------------------------------ |
| 404    | Smart group not found | The specified smart group ID does not exist |

***

## Smart Group Segments

Segments are categories that contain smart groups. Before creating a smart group, you need to know the segment ID.

### Get Segments

`GET /users/v1/smart-group-segments`

### Response Example

```json
{
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "data": {
    "segments": [
      {
        "id": 789,
        "name": "Departments"
      }
    ]
  }
}
```

### Create Segment

`POST /users/v1/smart-group-segments`

```json
{
  "name": "Locations"
}
```

[Smart Groups API reference](https://developer.connecteam.com/reference/get_smart_groups_users_v1_smart_groups_get)