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

{
  "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:

{
  "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

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

Success Response (201)

{
  "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)

{
  "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

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

Create Segment

POST /users/v1/smart-group-segments

{
  "name": "Locations"
}

Smart Groups API reference