Working with employees

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.

List employees

GET /v1/employees returns a cursor-paginated list of the people included in compliance. Service accounts are never listed.

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, comma-separated.
`email`	One email address, matched case-insensitively.
`onboardingStatus`	Onboarding statuses, comma-separated: `COMPLETE`, `INCOMPLETE`, `ONGOING`, `NOT_APPLICABLE`.

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.

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.
`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.

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.

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.

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

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.

Get started

Core concepts

Guides

List employees

Filters

Get an employee

Fields

Onboarding status

Tasks summary

Personal data

​List employees

​Filters

​Get an employee

​Fields

​Onboarding status

​Tasks summary

​Personal data

List employees

Filters

Get an employee

Fields

Onboarding status

Tasks summary

Personal data