> ## 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. # List employees > Returns the people in your workspace who are included in compliance. Only active employees are returned unless you set `status`. Service accounts are never returned. Filters combine with AND. To pass several values to one filter, separate them with commas: `group=Engineering,Sales`. Names and email addresses are personal data. Requires the `all:read` scope. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/employees openapi: 3.0.1 info: title: Secfix Public API description: >- Read and manage your Secfix compliance data from your own systems. Get an access token from `POST /oauth/token` with the OAuth 2.0 client credentials grant, then send it as a bearer token to the `/v1` endpoints. Errors are JSON objects with a stable `code` and the `requestId`. Lists use cursor pagination. contact: name: Secfix Support url: https://secfix.com email: support@secfix.com license: name: Proprietary url: https://secfix.com/license version: 1.0.0 servers: - url: https://api.secfix.com description: Production - url: https://api-staging.secfix.com description: Staging security: - bearerAuth: [] tags: - name: Employees description: >- Read the people in your workspace, with their employment status, group and onboarding progress. - name: Inventory description: >- Read assets in every inventory category. Create, update and delete `CUSTOM` and `INFORMATION` assets. - name: OAuth description: Get an access token with the OAuth 2.0 client credentials grant. - name: Groups description: >- Read employee groups, their member counts and the onboarding tasks assigned to them. - name: Health description: Check that the API is up. - name: Computers description: Read the computers in your workspace and their security settings. paths: /v1/employees: get: tags: - Employees summary: List employees description: >- Returns the people in your workspace who are included in compliance. Only active employees are returned unless you set `status`. Service accounts are never returned. Filters combine with AND. To pass several values to one filter, separate them with commas: `group=Engineering,Sales`. Names and email addresses are personal data. Requires the `all:read` scope. operationId: listEmployees parameters: - name: status in: query description: Employment status. Defaults to `ACTIVE`. required: false schema: type: string enum: - ACTIVE - TERMINATED - name: group in: query description: >- Group names, comma-separated, case-insensitive. An unknown name returns an empty page. required: false schema: type: string - name: groupId in: query description: Group `id`s from `GET /v1/groups`, comma-separated. required: false schema: type: string - name: email in: query description: One email address, case-insensitive. required: false schema: type: string - name: onboardingStatus in: query description: >- Onboarding statuses, comma-separated: `COMPLETE`, `INCOMPLETE`, `ONGOING` or `NOT_APPLICABLE`. required: false schema: type: string - name: pageSize in: query description: Results per page, 1-100. Defaults to 25. required: false schema: type: integer format: int32 - name: pageCursor in: query description: >- The `startCursor` or `endCursor` from a previous page of this list. Send the same filters as on that page. Leave it out for the first page. required: false schema: type: string responses: '200': description: Employees returned. headers: X-RateLimit-Limit: description: Requests allowed in the current rate-limit window. style: simple schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current rate-limit window. style: simple schema: type: integer X-RateLimit-Reset: description: Seconds until the rate-limit window resets. style: simple schema: type: integer content: application/json: schema: $ref: '#/components/schemas/CursorPageEmployeeDto' '400': description: >- A query parameter is invalid: an unknown `status` or `onboardingStatus`, a `groupId` that isn't a UUID, a `pageSize` outside 1-100, or a `pageCursor` that is malformed or came from a request with other filters. Code: `validation_failed`. content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '401': description: >- The access token is missing, invalid or replaced by a newer one. Code: `unauthorized` or `token_superseded`. content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '403': description: >- The access token doesn't have the scope this endpoint needs. Code: `scope_required`. content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '405': description: >- This path doesn't support the HTTP method. The `Allow` header lists the methods it supports. Code: `method_not_allowed`. headers: Allow: description: Comma-separated list of the HTTP methods this path supports. style: simple schema: type: string content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '429': description: >- Too many requests. Wait the number of seconds in `Retry-After`, then retry. Code: `rate_limited`. headers: Retry-After: description: Seconds to wait before retrying. style: simple schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: 'Unexpected server error. Code: `internal_error`.' content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' components: schemas: CursorPageEmployeeDto: type: object properties: pageInfo: $ref: '#/components/schemas/PageInfo' results: type: array description: The results on this page. items: $ref: '#/components/schemas/EmployeeDto' description: A page of results. ProblemDetail: type: object properties: code: type: string description: >- Error code for your error handling. It doesn't change between releases. example: not_found detail: type: string description: What went wrong in this request. example: No asset found for the given id. instance: type: string description: URI that identifies this occurrence of the error. example: /v1/inventory/assets/3f1c9a2e-8b4d-4e7a-9c1f-2a5b6c7d8e9f requestId: type: string description: >- The request's id, also sent in the `X-Request-Id` header. Include it when you contact support. example: req_01HZY8Q3M4N5P6R7S8T9V0W1X2 status: type: integer description: HTTP status code. format: int32 example: 404 title: type: string description: Short summary of the error type. example: Not Found type: type: string description: URI that identifies the error type. example: https://api.secfix.com/problems/not_found description: The JSON body of every error response. PageInfo: type: object properties: endCursor: type: string description: >- Cursor for the next page. Send it as `pageCursor`, with the same filters. Left out when there is no next page. example: AgAAAAX0bYb1Q0AAJDNmMWM5YTJlLTk0YjEtNGQ3Mi1hN2Q4LTEyMzQ1Njc4OWFiYw hasNextPage: type: boolean description: Whether there is a next page. example: true hasPreviousPage: type: boolean description: Whether there is a previous page. example: false pageCount: type: integer description: Number of results on this page. format: int32 example: 25 startCursor: type: string description: >- Cursor for the previous page. Send it as `pageCursor`, with the same filters. Left out when the page is empty and there is no previous page. example: AgEAAAX0bYb1Q0AAJDNmMWM5YTJlLTk0YjEtNGQ3Mi1hN2Q4LTEyMzQ1Njc4OWFiYw totalCount: type: integer description: >- Number of results that match your filters across all pages, at the time of the call. It doesn't depend on `pageCursor` or `pageSize`, and it changes when results are added or removed between calls. format: int64 example: 312 description: Pagination details. EmployeeDto: type: object properties: email: type: string description: Email address. example: alice@example.com endContractDate: type: string description: Contract end date. Left out when unknown. format: date example: '2026-12-31T00:00:00.000Z' groupId: type: string description: >- The `id` of the employee's group (see `GET /v1/groups`). Left out when the employee has no group. format: uuid example: 9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e groupName: type: string description: >- Name of the employee's group. Left out when the employee has no group. example: Engineering id: type: string description: The employee's id (UUID). format: uuid example: 3f1c9a2e-94b1-4d72-a7d8-123456789abc name: type: string description: Full name. example: Alice Doe onboardingStatus: type: string description: >- Onboarding status, computed from the employee's tasks in this workspace the same way as on the **People** page in Secfix. `NOT_APPLICABLE` for a terminated employee or one with no applicable tasks. If the employee belongs to more than one workspace, the **People** page currently also counts tasks from the other workspaces, so the two can differ. example: ONGOING enum: - COMPLETE - INCOMPLETE - ONGOING - NOT_APPLICABLE source: type: string description: Where the record comes from. example: GOOGLE_WORKSPACE enum: - GOOGLE_WORKSPACE - MANUAL - MS_OFFICE365 - RETOOL - HRIS startContractDate: type: string description: Contract start date. Left out when unknown. format: date example: '2025-01-15T00:00:00.000Z' status: type: string description: >- Employment status. `TERMINATED` once the employee is archived or deleted in Secfix. example: ACTIVE enum: - ACTIVE - TERMINATED tasksSummary: $ref: '#/components/schemas/TasksSummaryDto' description: A person in your workspace and their onboarding progress. TasksSummaryDto: type: object properties: deviceMonitoring: $ref: '#/components/schemas/CategorySummaryDto' policyAcceptance: $ref: '#/components/schemas/CategorySummaryDto' tasks: type: array description: >- The tasks that can be assigned to the employee and are enabled for your workspace's frameworks, in the order Secfix shows them. items: $ref: '#/components/schemas/EmployeeTaskDto' trainings: $ref: '#/components/schemas/CategorySummaryDto' description: Onboarding progress by task category, and the employee's tasks. CategorySummaryDto: type: object properties: completed: type: integer description: Number of tasks in this category the employee has completed. format: int32 example: 1 status: type: string description: Onboarding status of this category's tasks. example: ONGOING enum: - COMPLETE - INCOMPLETE - ONGOING - NOT_APPLICABLE total: type: integer description: >- Number of tasks in this category that apply to the employee: not marked N/A, and enabled for your workspace's frameworks. format: int32 example: 2 description: Onboarding progress in one task category. EmployeeTaskDto: type: object properties: category: type: string description: Task category. example: TRAINING enum: - MONITORING - TRAINING - POLICIES completedAt: type: string description: When the task was completed. Left out if it hasn't been. format: date-time example: '2026-03-02T09:15:00.000Z' expiresAt: type: string description: >- When the completed task expires, for recurring trainings. Left out if it doesn't expire. format: date-time example: '2027-03-02T00:00:00.000Z' key: type: string description: >- Task key, such as `SECURITY_AWARENESS_TRAINING`, `POLICIES_ACCEPTANCE` or `SECFIX_AGENT`. New keys can be added, so handle keys you don't know. example: SECURITY_AWARENESS_TRAINING name: type: string description: Task name as shown in Secfix. example: Security awareness training status: type: string description: >- Task status, as shown on the employee's page in Secfix. An expired task is `INCOMPLETE`. A hidden task is `NOT_APPLICABLE`, and so is every task of an active employee whose onboarding is `NOT_APPLICABLE`. A terminated employee's tasks keep their real status. example: COMPLETE enum: - COMPLETE - INCOMPLETE - NOT_APPLICABLE description: One onboarding task of the employee, as listed on their page in Secfix. securitySchemes: bearerAuth: type: http description: Access token from `POST /oauth/token`. scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.