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

Внимание. Сервис Яндекс Коннект больше не поддерживается. Directory API прекратит работу с 1 апреля 2023 года. С 24 марта доступность сервиса будет ограничена.

Для управления организациями, пользователями и доменами используйте сервис Яндекс 360 для бизнеса.

Документация API 360

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

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

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

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

GET /v6/departments/?
fields=<параметр1>,<параметр2>, ...
&page=<номер страницы>
&per_page=<число позиций на странице>
Host: https://api.directory.yandex.net
Authorization: OAuth <токен>
X-Org-ID: <идентификатор организации>
Accept: application/json
Параметры запроса
fields (необязательный)

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

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

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

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

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

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

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

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

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

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

OAuth 0c4181a7c2cf4521964a72ff57a34a07
X-Org-ID

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

Accept

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

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

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

{
  "page": <номер страницы ответа>,
  "total": <общее число отделов>,
  "per_page": <число отделов на одной странице ответа>,
  "result": [
    {
      "name": "<название отдела>",
      "email": "<email отдела>",
      "external_id": "<внешний идентификатор>",
      "removed": <true|false>,
      "id": <идентификатор отдела>,
      "parents": [
        {
          "name": "<название отдела>",
          "email": "<email отдела>",
          "external_id": "<внешний идентификатор>",
          "removed": <true|false>,
          "id": <идентификатор отдела>,
          "parent_id": <идентификатор родительского отдела>,
          "label": "<рассылка отдела>",
          "created": "<дата и время создания отдела>",
          "description": "<описание отдела>",
          "members_count": <количество сотрудников в отделе>
        },
        ...
      ],
      "label": "<рассылка отдела>",
      "created": "<дата и время создания отдела>",
      "parent": {
        "name": "<Текстовое название отдела>",
        "id": <идентификатор отдела>,
        "external_id": null,
        "removed": <true|false>,
        "parent_id": <идентификатор родительского отдела>
      },
      "description": "<описание отдела>",
      "members_count": <количество сотрудников в отделе>,
      "head": <идентификатор сотрудника-руководителя отдела>
    },
    ...
  ],
  "pages": 1,
  "links": {
            "next": "<адрес следующей страницы ответа>",
            "prev": "<адрес предыдущей страницы ответа>",
            "last": "<адрес последней страницы ответа>",
            "first": "<адрес первой страницы ответа>"
           }
}
Параметры ответа
page

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

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

total

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

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

per_page

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

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

result

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

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

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

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

Строка.

email

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

Строка

external_id

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

Строка.

removed

Признак удаленного отдела:

  • true — отдел удален;

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

Логиический.

id

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

Целое число.

parents

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

JSON-массив.

label

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

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

Строка.

created
Дата и время создания отдела в формате:
YYYY-MM-DDThh:mm:ss.ssssssZ

Строка.

parent

Объект с информацией о непосредственном родителе отдела.

JSON-объекет.

description

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

Строка.

members_count

Число сотрудников отдела без учета вложенных отделов.

Целое число.

head

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

Целое число.

Поля объектов массива parents
name

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

Строка.

email

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

Строка

external_id

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

Строка.

removed

Признак удаленного отдела:

  • true — отдел удален;

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

Логиический.

id

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

Целое число.

parent_id

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

Целое число.

label

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

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

Строка.

created
Дата и время создания отдела в формате:
YYYY-MM-DDThh:mm:ss.ssssssZ

Строка.

description

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

Строка.

members_count

Число сотрудников отдела без учета вложенных отделов.

Целое число.

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

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

Строка.

id

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

Целое число.

external_id

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

Строка.

removed

Признак удаленного отдела:

  • true — отдел удален;

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

Логиический.

parent_id

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

Целое число.

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

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

Строка.

email

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

Строка

external_id

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

Строка.

removed

Признак удаленного отдела:

  • true — отдел удален;

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

Логиический.

id

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

Целое число.

parents

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

JSON-массив.

label

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

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

Строка.

created
Дата и время создания отдела в формате:
YYYY-MM-DDThh:mm:ss.ssssssZ

Строка.

parent

Объект с информацией о непосредственном родителе отдела.

JSON-объекет.

description

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

Строка.

members_count

Число сотрудников отдела без учета вложенных отделов.

Целое число.

head

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

Целое число.

Поля объектов массива parents
name

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

Строка.

email

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

Строка

external_id

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

Строка.

removed

Признак удаленного отдела:

  • true — отдел удален;

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

Логиический.

id

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

Целое число.

parent_id

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

Целое число.

label

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

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

Строка.

created
Дата и время создания отдела в формате:
YYYY-MM-DDThh:mm:ss.ssssssZ

Строка.

description

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

Строка.

members_count

Число сотрудников отдела без учета вложенных отделов.

Целое число.

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

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

Строка.

id

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

Целое число.

external_id

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

Строка.

removed

Признак удаленного отдела:

  • true — отдел удален;

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

Логиический.

parent_id

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

Целое число.

pages

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

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

links

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

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

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

Строка.

prev

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

Строка.

last

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

Строка.

first

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

Строка.

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

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

Строка.

prev

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

Строка.

last

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

Строка.

first

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

Строка.