Skip to content

Люди и оргструктура ​

Семейство people.

norm_org_units ​

Дерево подразделений компании целиком. Состав подразделения — сигнал, по которому подразделение встречи определяется без модели: если большинство участников числится в одном подразделении, выбор сделан. Членство прямое, принадлежность верхним уровням выводится по полю parent_id. Доменное состояние not_ready — оргструктура не подключена: это ждёт человека, повторный вызов ничего не изменит.

Доступ: чтение · Списковый: нет · Версии контракта: 1

Аргументы

Аргументов нет.

Данные ответа (data)

ПолеПри успехеТипЗачем
unitsдасписок OrgUnitВсе подразделения компании; дерево строится по parent_id.
errorнетDomainErrorПочему данных нет: оргструктура не подключена.
Пример: успешный ответ
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:units",
      "label": "Подразделения"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T03:00:00.000Z",
    "ttl_sec": 86400,
    "stale": false
  },
  "data": {
    "units": [
      {
        "id": "u-root",
        "name": "Компания",
        "parent_id": null,
        "kind": "company",
        "sort_order": 0
      },
      {
        "id": "u-sales",
        "name": "Продажи",
        "parent_id": "u-root",
        "kind": "division",
        "code": "012",
        "sort_order": 10
      },
      {
        "id": "u-retail",
        "name": "Розница",
        "parent_id": "u-sales",
        "kind": "department",
        "sort_order": 20
      }
    ]
  }
}
Пример: случай «domain_error»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:units"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T03:00:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "data": {
    "error": {
      "code": "not_ready",
      "message": "Оргструктура не подключена: нет источника подразделений и людей. Это ждёт человека — повторный вызов ничего не изменит.",
      "retryable": false
    }
  }
}

norm_people_list ​

Сотрудники компании страницами. Поле id — то значение, которое передаётся в поля протокола с людьми (participant_ids, organizer_id). Почты приходят в нижнем регистре, и у одного человека их бывает несколько: сопоставляйте по любой из них. Для следующей страницы передайте page.next_cursor как cursor; нет курсора — люди дочитаны. total — сколько людей всего с учётом фильтров. role_id отбирает тех, у кого есть назначение с этой ролью: так отвечают на вопрос «кто занимает роль». unit_id отбирает по прямому членству, без спуска в дочерние подразделения: спускайтесь сами по дереву norm_org_units. active_only не передан — отдаются все, кого хранит сервер; true — скрыты те, у кого дата увольнения уже наступила. Доменное состояние not_ready — оргструктура не подключена.

Доступ: чтение · Списковый: да · Версии контракта: 1

Аргументы

ПолеОбязательноТипЗачем
active_onlyнетbooleanСкрыть уволенных; по умолчанию приходят все.
cursorнетstringКакую страницу прислать: next_cursor из прошлого ответа. Без него — первую.
limitнетintegerСколько записей прислать на одной странице.
role_idнетstringНайти тех, кто занимает эту роль: id из norm_roles_list.
unit_idнетstringНайти тех, кто числится в подразделении напрямую, без дочерних.

Данные ответа (data)

ПолеПри успехеТипЗачем
peopleдасписок PersonСотрудники этой страницы.
totalдаintegerСколько сотрудников подошло под фильтр всего, на всех страницах.
errorнетDomainErrorПочему данных нет: оргструктура не подключена.
Пример: успешный ответ
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:people",
      "label": "Сотрудники"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T03:00:00.000Z",
    "ttl_sec": 86400,
    "stale": false
  },
  "page": {
    "has_more": false
  },
  "data": {
    "total": 2,
    "people": [
      {
        "id": "p-1042",
        "name": "Анна Новикова",
        "aliases": [
          "Новикова А.",
          "a.novikova"
        ],
        "emails": [
          "a.novikova@example.com",
          "79001234567@example.com"
        ],
        "unit_ids": [
          "u-sales",
          "u-retail"
        ],
        "phone": "+7 900 123-45-67",
        "handles": [
          "@a_novikova",
          "anna.novikova"
        ],
        "manager_id": "p-1077",
        "hired_at": "2024-02-01",
        "assignments": [
          {
            "id": "a-1042-sales",
            "unit_id": "u-sales",
            "role_id": "r-cco",
            "role_name": "Коммерческий директор",
            "is_primary": true,
            "is_head": false,
            "started_at": "2024-02-01"
          },
          {
            "id": "a-1042-retail",
            "unit_id": "u-retail",
            "role_id": "r-head-retail",
            "role_name": "Руководитель розницы",
            "is_primary": false,
            "is_head": true
          }
        ],
        "extra": {
          "grade": "M2",
          "location": "Москва"
        }
      },
      {
        "id": "p-1077",
        "name": "Михаил Петров",
        "aliases": [
          "Петров М."
        ],
        "emails": [
          "m.petrov@example.com"
        ],
        "unit_ids": [
          "u-retail"
        ]
      }
    ]
  }
}
Пример: случай «domain_error»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:people"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T03:00:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "page": {
    "has_more": false
  },
  "data": {
    "error": {
      "code": "not_ready",
      "message": "Оргструктура не подключена: нет источника подразделений и людей. Это ждёт человека — повторный вызов ничего не изменит.",
      "retryable": false
    }
  }
}

norm_roles_list ​

Роли компании страницами: то, чем занимаются её люди. У компании с обычным кадровым учётом это справочник должностей, и у роли есть только идентификатор и название; компания, которая описывает роли смыслом, добавляет продукт роли, заказчика и подчинение. Идентификатор роли возвращается в назначениях сотрудника и принимается фильтром norm_people_list. unit_id отбирает роли, привязанные к подразделению; query — по части названия или другого названия без учёта регистра, total считается с учётом фильтров. Версий и текста описания в списке нет: карточку должности отдаёт norm_role_get. Пустой список — законный ответ компании, которая ролей не ведёт; not_ready означает, что оргструктура не подключена вовсе.

Доступ: чтение · Списковый: да · Версии контракта: 1

Аргументы

ПолеОбязательноТипЗачем
cursorнетstringКакую страницу прислать: next_cursor из прошлого ответа. Без него — первую.
limitнетintegerСколько записей прислать на одной странице.
queryнетstringНайти должности по части названия: без учёта регистра, по name и aliases.
unit_idнетstringПоказать только роли этого подразделения.

Данные ответа (data)

ПолеПри успехеТипЗачем
rolesдасписок RoleРоли этой страницы; пустой список — компания ролей не ведёт.
totalдаintegerСколько ролей подошло под фильтр всего, на всех страницах.
errorнетDomainErrorПочему данных нет: оргструктура не подключена.
Пример: успешный ответ
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:roles",
      "label": "Роли"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T03:00:00.000Z",
    "ttl_sec": 86400,
    "stale": false
  },
  "page": {
    "has_more": false
  },
  "data": {
    "total": 3,
    "roles": [
      {
        "id": "r-head-retail",
        "name": "Руководитель розницы",
        "aliases": [
          "Директор розничной сети"
        ],
        "product": "Выполненный план продаж розничной сети при сохранённой марже",
        "customer": "Коммерческий директор",
        "reports_to_role_id": "r-cco",
        "unit_id": "u-retail",
        "description": "Отвечает за выручку и маржу всех торговых точек."
      },
      {
        "id": "r-cco",
        "name": "Коммерческий директор"
      },
      {
        "id": "r-recruiter",
        "name": "Рекрутер",
        "aliases": [
          "Специалист по подбору"
        ],
        "reports_to_role_id": "r-head-hiring",
        "unit_id": "u-hiring",
        "description": "Ищет кандидатов и доводит их до выхода на работу.",
        "headcount_total": 4,
        "headcount_filled": 3,
        "grade": "7",
        "grade_note": "оклад по штатному расписанию",
        "substitute": "На время отсутствия замещает другой рекрутер отдела",
        "kpis": [
          {
            "name": "Срок закрытия своих вакансий",
            "target": "не больше 30 дней",
            "category": "Effectiveness"
          },
          {
            "name": "Доля кандидатов, прошедших испытательный срок",
            "target": "от 80 %",
            "category": "Quality"
          },
          {
            "name": "Закрытые вакансии за квартал",
            "target": "по плану отдела; от показателя зависит премия",
            "category": "Effectiveness",
            "id": "kpi-hires-q"
          }
        ],
        "updated_at": "2026-09-09T10:15:00+03:00"
      }
    ]
  }
}
Пример: случай «domain_error»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:roles"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T03:00:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "page": {
    "has_more": false
  },
  "data": {
    "error": {
      "code": "not_ready",
      "message": "Оргструктура не подключена: справочник ролей брать неоткуда. Это ждёт человека — повторный вызов ничего не изменит.",
      "retryable": false
    }
  }
}

norm_role_get ​

Карточка одной должности по id из norm_roles_list: должность целиком, руководящая должность и прямо подчинённые — ссылками с названиями, перечень версий описания со статусами и датами. subordinates: [] — подчинённых нет; поля нет — компания подчинение не отдаёт. Текста описания в карточке нет: его отдаёт norm_role_description. Людей в должности ищите в norm_people_list с role_id — дата вступления в должность лежит в их назначении; название подразделения — в norm_org_units. Доменные состояния: unknown_id — должности с таким id нет; not_ready — оргструктура не подключена.

Доступ: чтение · Списковый: нет · Версии контракта: 1

Аргументы

ПолеОбязательноТипЗачем
idдаstringКакую должность открыть: id из norm_roles_list.

Данные ответа (data)

ПолеПри успехеТипЗачем
roleдаRoleДолжность целиком, со всеми полями, какие ведёт компания.
descriptionsнетсписок RoleDescriptionVersionВерсии описания должности, новые первыми.
errorнетDomainErrorПочему карточки нет: должность не найдена или оргструктура не подключена.
reports_toнетRoleRefКому подчиняется должность; нет — не подчиняется или компания не ведёт.
subordinatesнетсписок RoleRefПрямо подчинённые должности; пустой список — подчинённых нет.
Пример: успешный ответ
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:roles/r-recruiter",
      "label": "Должности"
    }
  ],
  "freshness": {
    "as_of": "2026-10-05T03:00:00.000Z",
    "ttl_sec": 86400,
    "stale": false
  },
  "data": {
    "role": {
      "id": "r-recruiter",
      "name": "Рекрутер",
      "aliases": [
        "Специалист по подбору"
      ],
      "reports_to_role_id": "r-head-hiring",
      "unit_id": "u-hiring",
      "description": "Ищет кандидатов и доводит их до выхода на работу.",
      "headcount_total": 4,
      "headcount_filled": 3,
      "grade": "7",
      "grade_note": "оклад по штатному расписанию",
      "substitute": "На время отсутствия замещает другой рекрутер отдела",
      "kpis": [
        {
          "name": "Срок закрытия своих вакансий",
          "target": "не больше 30 дней",
          "category": "Effectiveness"
        },
        {
          "name": "Доля кандидатов, прошедших испытательный срок",
          "target": "от 80 %",
          "category": "Quality"
        },
        {
          "name": "Закрытые вакансии за квартал",
          "target": "по плану отдела; от показателя зависит премия",
          "category": "Effectiveness",
          "id": "kpi-hires-q"
        }
      ],
      "updated_at": "2026-09-09T10:15:00+03:00"
    },
    "reports_to": {
      "id": "r-head-hiring",
      "name": "Начальник отдела подбора и адаптации персонала"
    },
    "subordinates": [],
    "descriptions": [
      {
        "version": 3,
        "status": "active",
        "approved_at": "2026-03-12",
        "effective_from": "2026-03-16",
        "file_name": "ДИ_Рекрутер_v3.docx",
        "file_url": "https://docs.example.com/hr/positions/recruiter-v3.docx"
      },
      {
        "version": 2,
        "status": "superseded",
        "effective_from": "2025-02-01",
        "effective_to": "2026-03-15",
        "file_name": "ДИ_Рекрутер_v2.docx"
      },
      {
        "version": 1,
        "status": "superseded",
        "effective_from": "2024-01-10",
        "effective_to": "2025-01-31"
      }
    ]
  }
}
Пример: случай «domain_error»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:roles"
    }
  ],
  "freshness": {
    "as_of": "2026-10-05T03:00:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "data": {
    "error": {
      "code": "unknown_id",
      "message": "Должности r-unknown нет в справочнике: возьмите id из norm_roles_list.",
      "retryable": false
    }
  }
}

norm_role_description ​

Текст описания должности в Markdown окнами. Без version — действующая версия, а если действующей нет — самая новая по номеру; version — номер из descriptions карточки norm_role_get. max_chars — размер окна в символах (умолчание 12000, максимум 24000; те же значения, что у окна расшифровки, раздел limits слепка). Для следующего окна передайте page.next_cursor как cursor; нет курсора — текст дочитан. Повторный вызов с тем же курсором вернёт тот же текст, склейка окон равна полному тексту. Доменные состояния: unknown_id — нет должности или версии с таким номером; no_data — у должности нет ни одной версии описания; not_ready — оргструктура не подключена.

Доступ: чтение · Списковый: нет · Версии контракта: 1

Аргументы

ПолеОбязательноТипЗачем
role_idдаstringЧьё описание читать: id должности из norm_roles_list.
cursorнетstringОткуда продолжить чтение: next_cursor из прошлого ответа. Без него — с начала.
max_charsнетintegerСколько символов прислать за раз.
versionнетintegerКакую версию читать; без номера — действующую.

Данные ответа (data)

ПолеПри успехеТипЗачем
role_idдаstringЧьё это описание: тот же id, что передан во входе.
textдаstringMarkdown этого окна.
total_charsдаintegerДлина всего текста: по ней видно, сколько окон впереди.
versionдаintegerКакой версии этот текст: важно, когда номер не передавали.
errorнетDomainErrorПочему текста нет: должность или версия не найдены, описания нет, оргструктура не подключена.
file_nameнетstringИмя файла оригинала, если версия ведётся файлом.
file_urlнетstring (uri)Ссылка на оригинал в системе компании; может требовать там входа.
Пример: успешный ответ
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:roles/r-recruiter/descriptions/3",
      "label": "Должности"
    }
  ],
  "freshness": {
    "as_of": "2026-10-05T03:00:00.000Z",
    "ttl_sec": 86400,
    "stale": false
  },
  "page": {
    "has_more": true,
    "next_cursor": "v3:240"
  },
  "data": {
    "role_id": "r-recruiter",
    "version": 3,
    "total_chars": 5180,
    "text": "# Рекрутер\n\n## Зачем эта должность\n\nРекрутер ищет кандидатов на открытые вакансии отдела и доводит их до выхода на работу.\n\n## Обязанности\n\n- Открывает вакансию по заявке руководителя и согласует профиль кандидата.\n- Ведёт воронку кандидатов: поиск, скрининг, первичное интервью.\n",
    "file_name": "ДИ_Рекрутер_v3.docx",
    "file_url": "https://docs.example.com/hr/positions/recruiter-v3.docx"
  }
}
Пример: случай «domain_error»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:roles/r-cco"
    }
  ],
  "freshness": {
    "as_of": "2026-10-05T03:00:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "page": {
    "has_more": false
  },
  "data": {
    "error": {
      "code": "no_data",
      "message": "У должности «Коммерческий директор» описания нет: компания его не завела.",
      "retryable": false
    }
  }
}

norm_person_get ​

Карточка одного сотрудника целиком. Передайте id или email — хотя бы один обязателен, без обоих вызов отклоняется как invalid_input. Передали оба — карточку определяет id, почта игнорируется. Почта сравнивается без учёта регистра. Уволенный отдаётся всегда: вы спросили конкретного человека. Доменные состояния: unknown_user — ни идентификатор, ни почта не подошли; record_rejected — на эту почту в компании заведено больше одной карточки, и выбрать за человека нельзя; not_ready — оргструктура не подключена.

Доступ: чтение · Списковый: нет · Версии контракта: 1

Аргументы

ПолеОбязательноТипЗачем
emailнетstringКого открыть: почта сотрудника, в любом регистре.
idнетstringКого открыть: id сотрудника. Если передан, почта не нужна.

Данные ответа (data)

ПолеПри успехеТипЗачем
personдаPersonКарточка сотрудника целиком, в том числе уволенного.
errorнетDomainErrorПочему карточки нет: человек не найден или по почте их несколько.
Пример: успешный ответ
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:people/p-1042",
      "label": "Карточка сотрудника"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T03:00:00.000Z",
    "ttl_sec": 86400,
    "stale": false
  },
  "data": {
    "person": {
      "id": "p-1042",
      "name": "Анна Новикова",
      "aliases": [
        "Новикова А.",
        "a.novikova"
      ],
      "emails": [
        "a.novikova@example.com",
        "79001234567@example.com"
      ],
      "unit_ids": [
        "u-sales",
        "u-retail"
      ],
      "phone": "+7 900 123-45-67",
      "handles": [
        "@a_novikova",
        "anna.novikova"
      ],
      "manager_id": "p-1077",
      "hired_at": "2024-02-01",
      "assignments": [
        {
          "id": "a-1042-sales",
          "unit_id": "u-sales",
          "role_id": "r-cco",
          "role_name": "Коммерческий директор",
          "is_primary": true,
          "is_head": false,
          "started_at": "2024-02-01"
        },
        {
          "id": "a-1042-retail",
          "unit_id": "u-retail",
          "role_id": "r-head-retail",
          "role_name": "Руководитель розницы",
          "is_primary": false,
          "is_head": true
        }
      ],
      "extra": {
        "grade": "M2",
        "location": "Москва"
      }
    }
  }
}
Пример: случай «domain_error»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:people"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T03:00:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "data": {
    "error": {
      "code": "unknown_user",
      "message": "Ни идентификатор, ни почта не подошли ни к одному сотруднику. Проверьте значение: идентификаторы приходят из norm_people_list.",
      "retryable": false
    }
  }
}

norm_person_upsert ​

Создать или обновить карточку сотрудника. Ключ — id или email, правило то же, что у norm_person_get. По ключу id карточка только обновляется: нет такой — unknown_user. По ключу email карточка обновляется или создаётся; для создания обязательно имя, иначе ответ несёт record_rejected и поле name среди непринятых. Что делают переданные поля: поля нет во входе — оно не трогается; переданный массив заменяет прежний набор целиком; значение null у одиночного поля очищает его; внутри extra то же правило по каждому ключу. Непринятое поле — не отказ: остальное записано, а поле названо в rejected_fields с причиной. Доменные состояния: not_ready — запись профилей у компании не настроена; unknown_user — карточки по ключу id нет; record_rejected — ничего не записано (на почту заведено больше одной карточки, при создании нет имени, хранилище отвергло карточку целиком); unknown_field — компания не ведёт поле ядра, которое вы пытаетесь записать. Реализация вправе разрешить запись только привилегированным ролям и отвечать unauthorized_scope.

Доступ: запись · Списковый: нет · Версии контракта: 1

Аргументы

ПолеОбязательноТипЗачем
aliasesнетсписок stringДругие написания имени; заменяют прежние целиком.
assignmentsнетсписок AssignmentГде и в какой роли человек работает; заменяют прежние целиком.
emailнетstringЧью карточку обновить или создать: почта сотрудника.
emailsнетсписок stringВсе почты человека; заменяют прежние целиком.
extraнетobjectПоля, которые компания ведёт сверх контракта.
handlesнетсписок stringЛогины в мессенджерах и других системах; заменяют прежние целиком.
hired_atнетstring | null (date)Дата прихода в компанию; null — убрать.
idнетstringЧью карточку обновить: id сотрудника. По id карточка только обновляется.
manager_idнетstring | nullРуководитель: id сотрудника; null — убрать.
nameнетstringИмя; без него новую карточку не создать.
phoneнетstring | nullТелефон; null — убрать.
terminated_atнетstring | null (date)Дата ухода из компании; null — убрать.

Данные ответа (data)

ПолеПри успехеТипЗачем
createdдаbooleanСоздана ли карточка сейчас; false — обновлена существующая.
idдаstringid записанной карточки: пригодится, если её только что создали.
rejected_fieldsдасписок RejectedFieldКакие поля не записались и почему; остальное записано.
errorнетDomainErrorПочему ничего не записано.
urlнетstring (uri)Ссылка на карточку в системе компании.
Пример: успешный ответ
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:people/p-1042",
      "label": "Карточка сотрудника"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T09:31:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "data": {
    "id": "p-1042",
    "created": false,
    "url": "https://people.example.com/p-1042",
    "rejected_fields": [
      {
        "key": "extra.birthday",
        "reason": "поле не ведётся в карточке сотрудника"
      }
    ]
  }
}
Пример: случай «created»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:people/p-1103",
      "label": "Карточка сотрудника"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T09:31:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "data": {
    "id": "p-1103",
    "created": true,
    "url": "https://people.example.com/p-1103",
    "rejected_fields": []
  }
}
Пример: случай «domain_error»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "org:people"
    }
  ],
  "freshness": {
    "as_of": "2026-09-21T09:31:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "data": {
    "error": {
      "code": "unknown_user",
      "message": "Карточки с таким идентификатором нет. По ключу id карточка только обновляется; чтобы завести новую, передайте email и имя.",
      "retryable": false
    }
  }
}

Объекты семейства ​

Объекты, из которых состоят аргументы и ответы инструментов этого семейства.

OrgUnit ​

Подразделение. Идентификатор, название и родитель. У корневого подразделения родитель — null. Принадлежность верхним уровням выводится по цепочке родителей. Необязательные kind, code и sort_order — вид узла, код в учётной системе компании и порядок среди соседей.

ПолеОбязательноТипЗачем
idдаstringЧтобы сослаться на подразделение: в фильтрах, назначениях, протоколе.
nameдаstringНазвание подразделения.
parent_idдаstring | nullВ какое подразделение входит это; null — верхний уровень.
codeнетstringКод подразделения в учётной системе компании.
kindнетOrgUnitKindУровень подразделения: компания, дивизион, отдел, команда, группа.
sort_orderнетintegerВ каком порядке показывать подразделение среди соседей.

OrgUnitKind ​

Вид подразделения. Уровень узла в дереве: юридическое лицо, дивизион, отдел, команда, группа. Вид описателен: вложенность задаётся только полем parent_id.

Значения: company, division, department, team, group.

Person ​

Сотрудник. Идентификатор для полей протокола с людьми (participant_ids, organizer_id), имя, другие написания имени, все написания почты в нижнем регистре и прямое членство в подразделениях. handles — опознавательные строки вне почты (логины в мессенджерах): сопоставляйте их так же, как почту. Когда отданы назначения, unit_ids равно множеству их подразделений. Руководителя ищите так: явный manager_id; если его нет — человек с признаком is_head в основном подразделении; если и его нет — по цепочке reports_to_role_id роли основного назначения. extra — поля, которые ведёт сама компания: их состав контракт не описывает.

ПолеОбязательноТипЗачем
aliasesдасписок stringДругие написания имени: помогают узнать человека в расшифровке и в конференции.
emailsдасписок stringВсе почты человека в нижнем регистре: участника встречи находят по любой из них.
idдаstringЧтобы указать человека в протоколе (participant_ids, organizer_id) и в уведомлении.
nameдаstringИмя человека.
unit_idsдасписок stringВ каких подразделениях человек числится напрямую.
assignmentsнетсписок AssignmentГде и в какой роли человек работает.
extraнетobjectПоля, которые компания ведёт сверх контракта.
handlesнетсписок stringЛогины в мессенджерах и других системах: по ним человека узнают так же, как по почте.
hired_atнетstring (date)Когда человек пришёл в компанию.
manager_idнетstringКто руководитель человека: id сотрудника.
phoneнетstringТелефон человека.
terminated_atнетstring (date)Когда человек ушёл или уйдёт из компании.

Assignment ​

Назначение. Где человек числится и в какой роли. is_primary — основное место работы; is_head — человек руководит этим подразделением. Роль приходит идентификатором, а у компании без справочника должностей — только названием в role_name; назначение вовсе без роли означает «числится в подразделении».

ПолеОбязательноТипЗачем
is_headдаbooleanРуководит ли человек этим подразделением.
is_primaryдаbooleanОсновное ли это место работы человека.
unit_idдаstringВ каком подразделении человек числится.
ended_atнетstring (date)По какой день действовало назначение.
idнетstringНомер назначения в системе компании.
role_idнетstringВ какой роли человек здесь работает: id из norm_roles_list.
role_nameнетstringНазвание роли, если справочника ролей у компании нет.
started_atнетstring (date)С какого дня действует назначение.

Role ​

Роль. Чем человек занимается в компании. В обычном кадровом учёте роль — это должность, и у неё есть только идентификатор и название. Компания, которая описывает роли смыслом, добавляет product (что роль производит), customer (главный заказчик результата) и reports_to_role_id (кому роль подчиняется). Цикл в подчинении контракт не запрещает и не проверяет: обходя цепочку, защищайтесь от него сами. Компания со штатным расписанием добавляет headcount_total и headcount_filled (ставки по расписанию и занятые; занятых бывает больше ставок — совместительство, переходный период), grade и grade_note; компания, оценивающая работу, — kpis.

ПолеОбязательноТипЗачем
idдаstringЧтобы найти людей в этой роли: передайте в role_id списка сотрудников.
nameдаstringНазвание роли или должности.
aliasesнетсписок stringДругие названия той же роли.
customerнетstringКому нужен результат роли, если компания это описывает.
descriptionнетstringПояснение компании, чем занимается роль.
gradeнетstringГрейд должности в сетке компании, как его пишет компания: «7», «M2».
grade_noteнетstringПояснение к грейду: «оклад по штатному расписанию».
headcount_filledнетintegerСколько ставок занято людьми; может быть больше числа ставок.
headcount_totalнетintegerСколько ставок у должности по штатному расписанию: «занято N из M».
kpisнетсписок RoleKpiПо каким показателям оценивают работу в должности.
productнетstringЧто производит роль, если компания это описывает.
reports_to_role_idнетstringКакой роли подчиняется эта: так ищут руководителя.
substituteнетstringКто замещает на время отсутствия, словами.
unit_idнетstringК какому подразделению привязана роль.
updated_atнетstring (date-time)Когда должность последний раз менялась в системе компании.

RoleKpi ​

KPI должности. Показатель, по которому оценивают работу в должности: название и, если компания его ведёт, целевое значение словами. Категорию и идентификатор компания задаёт сама; контракт их словарь не описывает.

ПолеОбязательноТипЗачем
nameдаstringЧто измеряют: показать KPI человеку и агенту.
categoryнетstringКатегория показателя в компании: «Effectiveness», «Quality».
idнетstringИдентификатор показателя в системе компании: сослаться на него.
targetнетstringЦелевое значение словами: «не больше 30 дней», «от 80 %».

RoleDescriptionVersion ​

Версия описания должности. Номер, статус, даты утверждения и действия, файл оригинала. Текста здесь нет: его отдаёт norm_role_description окнами. Действующая версия у должности одна; контракт это правило описывает, но не проверяет — при двух действующих показывайте ту, что начала действовать позже. Описание, которое ведётся прямо в системе компании, файла не имеет.

ПолеОбязательноТипЗачем
statusдаRoleDescriptionStatusДействует ли версия.
versionдаintegerНомер версии: по нему запрашивают её текст в norm_role_description.
approved_atнетstring (date)Когда версия утверждена.
effective_fromнетstring (date)С какого дня версия действует.
effective_toнетstring (date)По какой день версия действовала; нет — действует сейчас или ещё не начиналась.
file_nameнетstringИмя файла оригинала, как его видит человек: «ДИ_Рекрутер_v3.docx».
file_urlнетstring (uri)Ссылка на оригинал в системе компании; может требовать там входа.

RoleDescriptionStatus ​

Статус версии описания. draft — на согласовании; active — действует; superseded — заменена новой версией. Утверждённая версия с будущей датой начала ещё не действует: её статус отличается от active, а дата видна в effective_from.

Значения: draft, active, superseded.

RoleRef ​

Ссылка на должность. Идентификатор и название другой должности: руководящей или подчинённой.

ПолеОбязательноТипЗачем
idдаstringОткрыть эту должность: id для norm_role_get.
nameдаstringНазвание должности: показать без листания справочника.

RejectedField ​

Непринятое поле. Поле, которое запись не приняла, и причина. Операция при этом выполнена.

ПолеОбязательноТипЗачем
keyдаstringКакое поле не записалось.
reasonдаstringПочему поле не записалось.