> ## 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 employees

> Read employees with their employment status, group, and onboarding progress.

The employees endpoints return the people in your workspace as the **People** page in Secfix shows
them: employment status, group, and onboarding progress. Employees are **read-only** in the API.

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

## List employees

`GET /v1/employees` returns a [cursor-paginated](https://developer-staging.secfix.com/pagination.md) list of the people included in
compliance. Service accounts are never listed.

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

By default the list returns **active** employees only. Pass `status=TERMINATED` to list terminated
employees instead.

## Filters

Filters combine with AND. A filter that takes several values accepts up to 50 of them,
comma-separated in one parameter, for example `group=Engineering,Sales`. More returns
`400 validation_failed`.

| Parameter | Filters by |
| - | - |
| `status` | Employment status: `ACTIVE` (default) or `TERMINATED`. One value. |
| `group` | Group names, comma-separated, matched case-insensitively. An unknown name returns an empty page. |
| `groupId` | Group ids from the [groups endpoints](https://developer-staging.secfix.com/guides/groups.md), comma-separated. |
| `email` | One email address, matched case-insensitively. |
| `onboardingStatus` | Onboarding statuses, comma-separated: `COMPLETE`, `INCOMPLETE`, `ONGOING`, `NOT_APPLICABLE`. |

```bash theme={null}
curl "https://api.secfix.com/v1/employees?group=Engineering,Sales&onboardingStatus=INCOMPLETE,ONGOING" \
  -H "Authorization: Bearer $TOKEN"
```

An unknown `status` or `onboardingStatus` value, or a `groupId` that isn't a UUID, returns
`400 validation_failed`.

## Get an employee

`GET /v1/employees/{id}` returns one employee by `id`. It returns **active and terminated** employees,
so you can still read someone after they leave. An unknown `id`, an `id` from another workspace, and a
service account all return `404 not_found`.

An employee's `id` is the same value as `ownerId` on computers and inventory assets. Use it to
[list an employee's computers](https://developer-staging.secfix.com/guides/computers.md#filter-by-owner).

## Fields

| Field | Meaning |
| - | - |
| `id` | Employee id. |
| `name` | Full name (**personal data**). |
| `email` | Email address (**personal data**). |
| `status` | `ACTIVE` or `TERMINATED`. An employee is `TERMINATED` once archived or deleted in Secfix. |
| `onboardingStatus` | Overall onboarding status. See [Onboarding status](#onboarding-status). |
| `groupName`, `groupId` | Name and id of the employee's group. Left out when the employee has no group. |
| `startContractDate`, `endContractDate` | Contract dates (`YYYY-MM-DD`). Left out when unknown. |
| `source` | Where the record comes from: `GOOGLE_WORKSPACE`, `MS_OFFICE365`, `HRIS`, `RETOOL`, or `MANUAL`. |
| `tasksSummary` | Onboarding progress per category, and the employee's tasks. See [Tasks summary](#tasks-summary). |

## Onboarding status

`onboardingStatus` follows the same rules as the status on the **People** page. It is calculated from
the employee's tasks in this workspace that apply to your workspace's frameworks:

| Value | Meaning |
| - | - |
| `COMPLETE` | Tasks are complete and none are open. |
| `INCOMPLETE` | Tasks are open and none are complete. |
| `ONGOING` | Some tasks are complete and some are open. |
| `NOT_APPLICABLE` | The employee is terminated, or has no applicable tasks. |

An expired task, such as a recurring training, counts as open.

> [!NOTE]
>
> If the same person is an employee in more than one of your workspaces, the **People** page currently
> also counts their tasks from the other workspaces. It can then show a different status than the
> API. The API counts only the tasks of the workspace your API key belongs to.

## Tasks summary

`tasksSummary` breaks onboarding down the way the employee's page in Secfix does:

* `trainings`, `deviceMonitoring`, `policyAcceptance`: progress per task category. Each has
  `total` (tasks of that category that apply to the employee), `completed`, and `status` (same values
  as `onboardingStatus`).
* `tasks`: the employee's tasks, in the order the Secfix app shows them. Each task has a `key`,
  `name`, `category` (`TRAINING`, `POLICIES`, or `MONITORING`), `status` (`COMPLETE`, `INCOMPLETE`,
  or `NOT_APPLICABLE`), and `completedAt` and `expiresAt` when they apply.

```json theme={null}
"tasksSummary": {
  "trainings": { "total": 2, "completed": 1, "status": "ONGOING" },
  "deviceMonitoring": { "total": 1, "completed": 1, "status": "COMPLETE" },
  "policyAcceptance": { "total": 1, "completed": 0, "status": "INCOMPLETE" },
  "tasks": [
    {
      "key": "SECURITY_AWARENESS_TRAINING",
      "name": "Security awareness training",
      "category": "TRAINING",
      "status": "COMPLETE",
      "completedAt": "2026-03-02T09:15:00Z",
      "expiresAt": "2027-03-02T00:00:00Z"
    }
  ]
}
```

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

> [!NOTE]
>
> A terminated employee's tasks keep their real status, even though their `onboardingStatus` is
> `NOT_APPLICABLE`.

## Personal data

`name` and `email` are personal data. Read access (`all:read`) returns them. No separate scope
protects them. Grant **Read** access only to API keys that may see your employees' data. See
[Scopes](https://developer-staging.secfix.com/scopes.md).


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