ConnectCloud Developers

The colleague directory (tenant:access)

GET /api/hr/v1/colleagues

Module: HR · operationId: listColleagues · Tag: Organisation · Auth: access token (Authorization: Bearer <accessToken>)

The active employees of the caller's tenant, the caller excluded, sorted by the display name: id, displayName, email, the org unit and only the values of fields marked visibleToColleagues (never restricted or switched-off fields). Needs no hr:read – but an active employee record of the caller, else 403 no_employee. q matches every word on its own (case-insensitive, part of a word) in the e-mail, the display name's fields and the text, phone and e-mail fields colleagues see.

Parameters

Name In Type Required Description
q query string Words of the name, e-mail or a field visible to colleagues
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 colleagues (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)

Fields of the 200 answer:

  • items (array of Colleague, required): Colleagues of this page
    • displayName (string, required): Display name (the e-mail when the name fields are empty)
    • email (string, required): E-mail address
    • fields (array of ColleagueField, required): Values of the fields visible to colleagues the person has, in the tenant's field order
      • key (string, required): Key of the field
      • kind (string, required): Kind of the field (FieldDef.kind) (one of text, longtext, number, date, datetime, bool, select, multiselect, url, phone, email)
      • label (string, required): Label of the field
      • value (any, required): The value: a string for text-like, phone, e-mail, date and URL fields, a number, a boolean, the option label of a select or the list of option labels of a multiselect
    • id (string, required): Id of the employee
    • unit (object): Org unit the colleague is placed in (omitted when none)
      • id (string, required): Id of the org unit
      • name (string, required): Name of the org unit
  • total (integer, required): Number of all matching colleagues

Example 200 answer:

{
  "items": [
    {
      "displayName": "Jonas Bauer",
      "email": "jonas.bauer@muster-it.example",
      "fields": [
        {
          "key": "phone",
          "kind": "phone",
          "label": "Telefon",
          "value": "+49 941 123450-21"
        },
        {
          "key": "mobile",
          "kind": "phone",
          "label": "Mobil",
          "value": "+49 160 2230051"
        }
      ],
      "id": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
      "unit": {
        "id": "2e4a6c8e-0a2c-4e4a-8c6e-0a2c4e6a8c72",
        "name": "Technik"
      }
    },
    {
      "displayName": "Sophie Huber",
      "email": "sophie.huber@muster-it.example",
      "fields": [
        {
          "key": "phone",
          "kind": "phone",
          "label": "Telefon",
          "value": "+49 941 123450-17"
        }
      ],
      "id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
      "unit": {
        "id": "0c2e4a6c-8e0a-4c2e-9a4c-6e8a0c2e4a71",
        "name": "Service Desk"
      }
    }
  ],
  "total": 2
}

Example request

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

View as Markdown · Interactive reference · OpenAPI