## List employees (hr:read)

`GET /api/hr/v1/employees`

Module: HR · operationId: `listEmployees` · Tag: Employees · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  | Searches email and non-restricted text fields |
| `status` | query | string |  | (one of `active`, `disabled`) |
| `groupId` | query | string |  |  |
| `roleId` | query | string |  | Direct or through a group |
| `orgUnitId` | query | string |  | Only employees of this org unit |
| `subUnits` | query | boolean |  | Include the unit's sub-units |
| `team` | query | string |  | `mine` = only the people the caller is responsible for (one of `mine`) |
| `sort` | query | string |  | `email`, `status`, `createdAt`, `updatedAt` or `cf.<key>`; prefix `-` for descending |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  | (default `0`) |

### Responses

- **200** A page of employees (`application/json`)

Fields of the 200 answer:

- `items` (array of Employee): Employees of this page
  - `addressId` (string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HR
  - `addressUnmatched` (boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.
  - `createdAt` (string (date-time)): When the employee was created
  - `createdBy` (string): Who created the employee (e-mail of the caller)
  - `customFields` (object): Values of the tenant-defined fields by field key; restricted fields only with hr:write
  - `displayName` (string): Name built from the tenant's display fields (falls back to the e-mail)
  - `email` (string): E-mail address; the sign-in identity
  - `groupIds` (array of string): Ids of the groups the employee belongs to
  - `id` (string): Id of the employee
  - `invitationSent` (boolean): Only on create: whether the invitation mail was sent
  - `lastLoginAt` (string (date-time)): Last sign-in
  - `roleIds` (array of string): Ids of the directly assigned roles
  - `status` (string): disabled employees cannot sign in (one of `active`, `disabled`)
  - `tenantColor` (string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answer
  - `updatedAt` (string (date-time)): When the employee was last changed
  - `updatedBy` (string): Who last changed the employee (e-mail of the caller)
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `total` (integer): Number of all matching employees

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
      "addressUnmatched": false,
      "createdAt": "2023-10-12T09:14:00Z",
      "createdBy": "clara.becker@muster-it.example",
      "customFields": {
        "department": "service",
        "entry_date": "2023-11-02",
        "first_name": "Sophie",
        "last_name": "Huber",
        "personnel_number": "1017",
        "phone": "+49 941 123450-17",
        "position": "Service Desk Agentin"
      },
      "displayName": "Sophie Huber",
      "email": "sophie.huber@muster-it.example",
      "groupIds": [
        "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
      ],
      "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "lastLoginAt": "2026-11-19T07:28:41Z",
      "roleIds": [
        "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
      ],
      "status": "active",
      "updatedAt": "2026-09-01T08:02:00Z",
      "updatedBy": "clara.becker@muster-it.example",
      "version": 6
    },
    {
      "addressId": "9a1c3e5b-7d9f-4a1c-8e3b-5d7f9a1c3e22",
      "addressUnmatched": false,
      "createdAt": "2024-10-21T13:40:00Z",
      "createdBy": "clara.becker@muster-it.example",
      "customFields": {
        "department": "service",
        "entry_date": "2024-11-04",
        "first_name": "Elias",
        "last_name": "Gruber",
        "mobile": "+49 160 2230054",
        "personnel_number": "1021",
        "position": "Service Desk Agent"
      },
      "displayName": "Elias Gruber",
      "email": "elias.gruber@muster-it.example",
      "groupIds": [
        "21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91",
        "23c5e7a9-1b3d-4f5a-9c7e-9b1d3f5a7c92"
      ],
      "id": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
      "lastLoginAt": "2026-11-18T07:02:13Z",
      "roleIds": [
        "13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
      ],
      "status": "active",
      "updatedAt": "2025-11-03T09:15:00Z",
      "updatedBy": "clara.becker@muster-it.example",
      "version": 3
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/employees' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
