ConnectCloud Developers

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:

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

View as Markdown · Interactive reference · OpenAPI