Просмотреть список сотрудников

Ограничение.

Чтобы выполнить запрос, приложению требуется разрешение на чтение данных о сотрудниках. Убедитесь, что вы указали его при настройке OAuth.

Запрос позволяет получить информацию о сотрудниках определенной команды, отдела или всей организации. Вы можете запросить как полную информацию о сотрудниках, так и только необходимые вам поля.

Формат запроса

Для получения списка сотрудников используйте HTTP-запрос с методом GET:

GET /v6/users/?
fields=<параметр1>,<параметр2>, ...
&id=<id1>,<id2>, ...
&nickname=<nickname1,nickname2,... >
&department_id=<id_отдела1>,<id_отдела2>, ...
&recursive_department_id=<id_отдела1>,<id_отдела2>, ...
&group_id=<id_команды1>,<id_команды2>,...
&recursive_group_id=<id_команды1>,<id_команды2>,...
&is_dismissed=<true|false|ignore>
&page=<номер страницы>
&per_page=<число позиций на странице>
Host: https://api.directory.yandex.net
Authorization: OAuth <токен>
X-Org-ID: <идентификатор организации>
Accept: application/json
Параметры запроса
fields (необязательный)

Список полей сотрудников, которые вы хотите получить. Список доступных параметров сотрудника перечислен в параметре ответа result.

Тип данных: строка.

Внимание.

Чтобы в ответе получить нужный параметр fields, передайте его в запросе. Если параметр fields не указан, ответ будет содержать только идентификаторы сотрудников.

id (необязательный)

Идентификаторы сотрудников, о которых вы хотите получить информацию.

Тип данных: целое число.

nickname (необязательный)

Логины сотрудников, о которых вы хотите получить информацию.

Тип данных: строка.

department_id (необязательный)

Идентификаторы отдела, информацию о сотрудниках которых вы запрашиваете. Ответ содержит сведения только сотрудниках самого отдела. Сотрудники подотделов в ответе отсутствуют.

Тип данных: целое число.

recursive_department_id (необязательный)

Идентификаторы отделов, информацию о сотрудниках которых вы запрашиваете. Ответ содержит сведения о сотрудниках как самого отдела, так и всех его подотделов.

Тип данных: целое число.

group_id (необязательный)

Идентификаторы команд, информацию об участниках которых вы запрашиваете. Ответ содержит сведения только об участниках самой команды. Участники вложенных команд в ответе отсутствуют.

Тип данных: целое число.

recursive_group_id (необязательный)

Идентификаторы команд, информацию об участниках которых вы запрашиваете. Ответ содержит сведения об участниках как самой команды, так и всех вложенных команд.

Тип данных: целое число.

is_dismissed (необязательный)

Включать ли в ответ уволенных сотрудников:

  • true — ответ содержит сведения только об уволенных сотрудниках;

  • false (значение по умолчанию) — ответ не содержит сведения об уволенных сотрудниках;
  • ignore — ответ содержит сведения обо всех сотрудниках;

Тип данных: строка.

page (необязательный)

Номер страницы ответа. Значение по умолчанию — 1.

per_page (необязательный)

Число сотрудников на одной странице. Максимальное значение — 1000. Значение по умолчанию — 20.

Заголовки запроса
Host

Адрес узла, предоставляющего API:

https://api.directory.yandex.net
Authorization

OAuth-токен в формате OAuth <значение токена>, например:

OAuth 0c4181a7c2cf4521964a72ff57a34a07
X-Org-ID

Идентификатор организации. Заголовок необходимо передавать только если запрос выполняется от имени администратора нескольких организаций.

Accept

Допустимый формат ответа. Должен иметь значение application/json.

Запрос списка всех действующих сотрудников организации с указанием необходимых полей:

  • Используется HTTP-метод GET.

  • Ответ содержит только имя, пол, должность и контакты сотрудника: fields=name,gender,position,contacts.

  • Ответ не должен содержать уволенных сотрудников: is_dismissed=false

GET /v6/users/?fields=name,gender,position,contacts&is_dismissed=false
Host: https://api.directory.yandex.net
Authorization: OAuth 0c4181a7c2cf4521964a72ff57a34a07
Accept: application/json

Формат ответа

В случае успешного выполнения запроса API возвращает ответ с кодом 200. Тело ответа содержит результаты в формате JSON:

{
  "page": <номер страницы>,
  "total": <число найденных сотрудников>,
  "per_page": <число сотрудников на странице>,
  "result": [
    {
      "is_robot": <true|false>,
      "external_id": null,
      "position": "<должность>",
      "departments": [
        {
          "id": <id отдела>
        },  
        ...        
      ],
      "org_id": <id организации>,
      "gender": "<male|female>",
      "created": "<время и дата создания сотрудника>",
      "name": {
        "first": "<Имя>",
        "last": "<Фамилия>",
        "middle": "<Отчество>"
      },
      "about": "<описание сотрудника>",
      "nickname": "<логин>",
      "groups": [
        {
          "id": <id команды>
        },
        ...
      ],
      "is_admin": <true|false>,
      "birthday": "<ГГГГ-ММ-ДД>",
      "department_id": 3,
      "email": "<основной email>",
      "department": {
        "id": <id отдела>
      },
      "contacts": [
        {
          "value": "<значение контакта>",
          "type": "<email|phone_extension|phone|site|icq|twitter|facebook|skype>",
          "main": <true|false>,
          "alias": <true|false>,
          "synthetic": <true|false>
        },
        ...
      ],
      "aliases": [
        "<псевдоним1>",
        "<псевдоним2>",
        ...
      ],
      "id": <id сотрудника>,
      "is_dismissed": <true|false>,
      "is_enabled": <true|false>
    },
    ...
  ],
  "pages": 1,
  "links": {
            "next": "<адрес следующей страницы ответа>",
            "prev": "<адрес предыдущей страницы ответа>",
            "last": "<адрес последней страницы ответа>",
            "first": "<адрес первой страницы ответа>"
           }
}
Параметры ответа
page

Номер страницы ответа.

Тип данных: целое число.

total

Общее число найденных сотрудников.

Тип данных: целое число.

per_page

Максимальное число сотрудников, информация о которых содержится на одной странице.

Тип данных: целое число.

result

Массив, содержащий сведения о сотрудниках. Состоит из объектов, каждый из которых содержит информацию о найденном сотруднике

С помощью параметра fields запроса вы можете ограничить перечень полей сотрудника, содержащихся в ответе. Если параметр fields не указан, ответ содержит только идентификаторы сотрудников.

Параметр Описание Тип данных
is_robot

Признак служебных сотрудников-ботов:

  • true — бот;

  • false — человек.

Логический.

external_id

Произвольный идентификатор, который вы можете задать при создании сотрудника.

Строка.

position Должность сотрудника.

Строка.

departments Массив объектов с информацией об отделах, к которым относится сотрудник (включая вышестоящие отделы). JSON-массив.
org_id

Идентификатор организации, в которой состоит сотрудник.

Целое число.

gender

Пол сотрудника:

  • male — мужской;

  • female — женский

  • null — пол не указан.

Строка.

created
Дата и время создания сотрудника в формате
YYYY-MM-DDThh:mm:ss.ssssssZ
Строка
name Объект с информацией об имени сотрудника. Объект.
about

Содержимое поля О сотруднике.

Строка.

nickname

Логин сотрудника.

Строка

groups Массив объектов с информацией о командах, в которых состоит сотрудник.

Массив.

is_admin Признак администратора организации:
  • true — администратор;

  • false — рядовой пользователь.

Логический.

birthday

Дата рождения сотрудника в формате

YYYY-MM-DD

Строка.

department_id

Идентификатор отдела, в котором состоит сотрудник.

Целое число.

email

Основной адрес электронной почты сотрудника.

Строка.

department
Объект с информацией об отделе, в котором состоит сотрудник. По умолчанию содержит только поле id. Список полей можно расширить, передав в запросе параметр
fields=department.<имя поля>
. Подробнее о полях отделов читайте в разделе Просмотреть параметры отдела.

JSON-объект.

contacts Массив объектов с информацией о контактах сотрудника.

Массив.

aliases Перечень псевдонимов сотрудника.

Массив.

id Идентификатор сотрудника.

Целое число.

is_dismissed

Статус сотрудника:

  • true — уволенный;

  • false — действующий.

Чтобы восстановить сотрудника, создайте новый профиль с прежним логином.

При увольнении данные об аккаунте сотрудника удаляются.

Логический.

is_enabled

Статус аккаунта сотрудника:

  • true — активен;

  • false — заблокирован.

Логический.

Поля объектов массива departments
id

Идентификатор отдела, к которому относится сотрудник.

Целое число.

Поля объекта name
first

Имя сотрудника

Строка.

last

Фамилия сотрудника

Строка.

middle

Отчество сотрудника

Строка.

Поля объектов массива groups
id

Идентификатор команды, в которой состоит сотрудник.

Целое число.

Поля объекта department
id

Идентификатор отдела.

Целое число.

name

Текстовое название отдела, например, «Отдел разработки».

Строка.

description

Описание отдела.

Строка.

head_id

Идентификатор сотрудника-руководителя отдела.

Целое число.

label

Имя почтового ящика отдела. Имя может состоять только из символов латинского алфавита, цифр, знаков минус и нижнего подчеркивания.

Например, адрес ящика с именем new-department будет new-department@<ваш-домен>.tld.

Строка.

email

Коллективный почтовый адрес отдела.

Строка

parents

Массив объектов с информацией о родительских отделах. Содержит информацию обо всех вышестоящих отделах

JSON-массив.

Поля объектов массива contacts
value

Адрес ресурса, по которому расположен контакт.

Строка.

type

Тип контакта. Может принимать одно из значений:

  • email;

  • phone_extension;

  • phone;

  • site;

  • icq;

  • twitter;

  • facebook;

  • skype.

Строка.

main

Признак основного контакта:

  • true — основной;

  • false — альтернативный.

У сотрудников может быть только один основной контакт каждого типа.

Логический.

alias

Если у сотрудника есть псевдоним, для него автоматически создается контакт типа email:

  • true — контакт создан на основе псевдонима;

  • false — контакт создан вручную.

Логический.

synthetic

Признак автоматически созданного контакта:

  • true — контакт создан автоматически;

  • false — контакт создан вручную.

Логический.

Параметр Описание Тип данных
is_robot

Признак служебных сотрудников-ботов:

  • true — бот;

  • false — человек.

Логический.

external_id

Произвольный идентификатор, который вы можете задать при создании сотрудника.

Строка.

position Должность сотрудника.

Строка.

departments Массив объектов с информацией об отделах, к которым относится сотрудник (включая вышестоящие отделы). JSON-массив.
org_id

Идентификатор организации, в которой состоит сотрудник.

Целое число.

gender

Пол сотрудника:

  • male — мужской;

  • female — женский

  • null — пол не указан.

Строка.

created
Дата и время создания сотрудника в формате
YYYY-MM-DDThh:mm:ss.ssssssZ
Строка
name Объект с информацией об имени сотрудника. Объект.
about

Содержимое поля О сотруднике.

Строка.

nickname

Логин сотрудника.

Строка

groups Массив объектов с информацией о командах, в которых состоит сотрудник.

Массив.

is_admin Признак администратора организации:
  • true — администратор;

  • false — рядовой пользователь.

Логический.

birthday

Дата рождения сотрудника в формате

YYYY-MM-DD

Строка.

department_id

Идентификатор отдела, в котором состоит сотрудник.

Целое число.

email

Основной адрес электронной почты сотрудника.

Строка.

department
Объект с информацией об отделе, в котором состоит сотрудник. По умолчанию содержит только поле id. Список полей можно расширить, передав в запросе параметр
fields=department.<имя поля>
. Подробнее о полях отделов читайте в разделе Просмотреть параметры отдела.

JSON-объект.

contacts Массив объектов с информацией о контактах сотрудника.

Массив.

aliases Перечень псевдонимов сотрудника.

Массив.

id Идентификатор сотрудника.

Целое число.

is_dismissed

Статус сотрудника:

  • true — уволенный;

  • false — действующий.

Чтобы восстановить сотрудника, создайте новый профиль с прежним логином.

При увольнении данные об аккаунте сотрудника удаляются.

Логический.

is_enabled

Статус аккаунта сотрудника:

  • true — активен;

  • false — заблокирован.

Логический.

Поля объектов массива departments
id

Идентификатор отдела, к которому относится сотрудник.

Целое число.

Поля объекта name
first

Имя сотрудника

Строка.

last

Фамилия сотрудника

Строка.

middle

Отчество сотрудника

Строка.

Поля объектов массива groups
id

Идентификатор команды, в которой состоит сотрудник.

Целое число.

Поля объекта department
id

Идентификатор отдела.

Целое число.

name

Текстовое название отдела, например, «Отдел разработки».

Строка.

description

Описание отдела.

Строка.

head_id

Идентификатор сотрудника-руководителя отдела.

Целое число.

label

Имя почтового ящика отдела. Имя может состоять только из символов латинского алфавита, цифр, знаков минус и нижнего подчеркивания.

Например, адрес ящика с именем new-department будет new-department@<ваш-домен>.tld.

Строка.

email

Коллективный почтовый адрес отдела.

Строка

parents

Массив объектов с информацией о родительских отделах. Содержит информацию обо всех вышестоящих отделах

JSON-массив.

Поля объектов массива contacts
value

Адрес ресурса, по которому расположен контакт.

Строка.

type

Тип контакта. Может принимать одно из значений:

  • email;

  • phone_extension;

  • phone;

  • site;

  • icq;

  • twitter;

  • facebook;

  • skype.

Строка.

main

Признак основного контакта:

  • true — основной;

  • false — альтернативный.

У сотрудников может быть только один основной контакт каждого типа.

Логический.

alias

Если у сотрудника есть псевдоним, для него автоматически создается контакт типа email:

  • true — контакт создан на основе псевдонима;

  • false — контакт создан вручную.

Логический.

synthetic

Признак автоматически созданного контакта:

  • true — контакт создан автоматически;

  • false — контакт создан вручную.

Логический.

pages

Общее число страниц с результатами выполнения запроса.

Тип данных: целое число.

links

Объект, содержащий информацию о страницах ответа.

Параметр Описание Тип данных
next

Адрес следующей страницы ответа.

Строка.

prev

Адрес предыдущей страницы ответа.

Строка.

last

Адрес последней страницы ответа.

Строка.

first

Адрес первой страницы ответа.

Строка.

Параметр Описание Тип данных
next

Адрес следующей страницы ответа.

Строка.

prev

Адрес предыдущей страницы ответа.

Строка.

last

Адрес последней страницы ответа.

Строка.

first

Адрес первой страницы ответа.

Строка.