## 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:

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

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