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 pageaddressId(string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HRaddressUnmatched(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 createdcreatedBy(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:writedisplayName(string): Name built from the tenant's display fields (falls back to the e-mail)email(string): E-mail address; the sign-in identitygroupIds(array of string): Ids of the groups the employee belongs toid(string): Id of the employeeinvitationSent(boolean): Only on create: whether the invitation mail was sentlastLoginAt(string (date-time)): Last sign-inroleIds(array of string): Ids of the directly assigned rolesstatus(string): disabled employees cannot sign in (one ofactive,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 answerupdatedAt(string (date-time)): When the employee was last changedupdatedBy(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:
{
"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
curl -X GET 'https://api.mbcom.cloud/api/hr/v1/employees' \
-H "Authorization: Bearer $ACCESS_TOKEN"