> ## Documentation Index
> Fetch the complete documentation index at: https://developer-staging.secfix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with groups

> Read employee groups, their member counts, onboarding tasks, and settings.

The groups endpoints return your employee groups as the **Groups** page in Secfix shows them: member
counts, the onboarding tasks assigned to each group, and each group's settings. Groups are
**read-only** in the API.

Reads require **Read** access (`all:read`). See [Scopes](https://developer-staging.secfix.com/scopes.md).

## List groups

`GET /v1/groups` returns a [cursor-paginated](https://developer-staging.secfix.com/pagination.md) list of groups, oldest first.

```bash theme={null}
curl "https://api.secfix.com/v1/groups?pageSize=50" \
  -H "Authorization: Bearer $TOKEN"
```

To filter by name, pass `name` with up to 50 group names, comma-separated. Names are matched
case-insensitively:

```bash theme={null}
curl "https://api.secfix.com/v1/groups?name=Engineering,Sales" \
  -H "Authorization: Bearer $TOKEN"
```

To list a group's employees, pass its `id` as `groupId` to
[`GET /v1/employees`](https://developer-staging.secfix.com/guides/employees#filters).

## Fields

| Field | Meaning |
| - | - |
| `id` | Group id. |
| `name` | Group name. |
| `isDefault` | `true` for your workspace's default group, which new employees join. |
| `memberType` | Who the group holds: `PEOPLE` or `SERVICE_ACCOUNTS`. Left out when not set. A group without a `memberType` counts no members. |
| `employeeCount` | Active members of the group who are included in compliance. This is the count the **Groups** page shows. |
| `createdAt` | When the group was created. Left out for older groups created before Secfix recorded this. |
| `tasks` | The onboarding tasks assigned to the group. See [Tasks](#tasks). |

## Tasks

`tasks` lists the onboarding tasks the **Groups** page shows on the group: trainings first, then device
monitoring, then policies. Each task has a `key`, `name`, and `category` (`TRAINING`, `MONITORING`,
or `POLICIES`).

A task is listed when it is assigned to the group and enabled for your workspace's frameworks. Policy
acceptance is listed only when at least one policy is assigned to the group.

Task keys are stable, but new keys may be added. Treat an unknown key as opaque.

## Get a group

`GET /v1/groups/{id}` returns one group with its settings, as the group's settings in the Secfix app
show them. An unknown `id` returns `404 not_found`.

```bash theme={null}
curl "https://api.secfix.com/v1/groups/$GROUP_ID" \
  -H "Authorization: Bearer $TOKEN"
```

It returns the list fields plus:

| Field | Meaning |
| - | - |
| `trainings` | Every training enabled for your workspace's frameworks, in the order the Secfix app shows them. Each has `key`, `name`, `description` (when set), and `enabled` (whether it's assigned to this group). |
| `deviceMonitoring` | `enabled` (whether device monitoring is assigned to this group) and `subTasks`: its steps in the order the Secfix app shows them, such as installing the Secfix agent or configuring MDM. Each step has `key`, `name`, and `enabled`. |
| `policyAcceptance` | `enabled` (whether policy acceptance is assigned to this group) and `policies`: the approved policies the group's members must accept, each with `id` and `name`. Secfix policies come first, then custom policies, each sorted by name. |

```json theme={null}
{
  "id": "9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e",
  "name": "Engineering",
  "isDefault": false,
  "memberType": "PEOPLE",
  "employeeCount": 12,
  "tasks": [
    { "key": "SECURITY_AWARENESS_TRAINING", "name": "Security awareness training", "category": "TRAINING" }
  ],
  "trainings": [
    { "key": "SECURITY_AWARENESS_TRAINING", "name": "Security awareness training", "enabled": true }
  ],
  "deviceMonitoring": {
    "enabled": true,
    "subTasks": [
      { "key": "SECFIX_AGENT", "name": "Install the Secfix agent", "enabled": true }
    ]
  },
  "policyAcceptance": {
    "enabled": true,
    "policies": [
      { "id": "5e8f0a1b-2c3d-4e5f-9a6b-7c8d9e0f1a2b", "name": "Acceptable Use Policy" }
    ]
  }
}
```

> [!NOTE]
>
> When device monitoring isn't assigned to the group, its steps show `enabled: false`. The MDM step is
> the exception: it keeps its own value.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.