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 pagedisplayName(string, required): Display name (the e-mail when the name fields are empty)email(string, required): E-mail addressfields(array of ColleagueField, required): Values of the fields visible to colleagues the person has, in the tenant's field orderkey(string, required): Key of the fieldkind(string, required): Kind of the field (FieldDef.kind) (one oftext,longtext,number,date,datetime,bool,select,multiselect,url,phone,email)label(string, required): Label of the fieldvalue(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 employeeunit(object): Org unit the colleague is placed in (omitted when none)id(string, required): Id of the org unitname(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"