飞书开放平台 Server API 文档

主题

批量获取部门信息 ​

该接口支持传入多个部门ID，返回每个部门的详细信息（如名称、负责人、子部门等）。

Tip: 注意：

  • 本接口支持tenant_access_token和user_access_token。
    • 使用tenant_access_token时，数据权限遵循应用的通讯录权限范围，返回的字段数据为应用有权限的字段。可通过获取应用通讯录权限范围配置确定应用的通讯录权限范围。 > - 使用user_access_token时，默认为管理员用户，将校验管理员管理范围。当用户有多个管理员身份均可查看部门信息时，管理员管理范围取最大集。管理员权限可查看帮助中心文档： 管理员创建管理员角色及分配权限
  • 为增强飞书组织架构 OpenAPI 的灵活性，于 2024 年 10 月 21 日对该 API 接口做出了更新升级，升级内容包括：优化查询已删除部门信息的返回数据结构。
    • 升级前，查询已删除部门的信息时，不会返回部门负责人信息；升级后，查询已删除部门的信息时，返回数据中将包括部门负责人信息。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/directory/v1/departments/mget
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用directory:department:read 调用 API 获取部门信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 directory:department.base:read 查看部门基础信息 directory:department.count:read 查看部门成员与子部门计数 directory:department.custom_field:read 查看部门自定义字段信息 directory:department.data_source:read 查看部门数据来源 directory:department.department_path:read 查看部门路径信息 directory:department.external_id:read 查看部门自定义 ID directory:department.has_child:read 查看部门是否有子部门 directory:department.leader:read 查看部门负责人信息 directory:department.name:read 查看部门的名称 directory:department.order_weight:read 查看部门排序权重 directory:department.organization:read 查看部门组织架构信息 directory:department.parent_id:read 查看部门的父部门 ID directory:department.status:read 查看部门的停启用状态 directory:employee.base.external_id:read 查看员工自定义 ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

查询参数 ​

名称类型必填描述
employee_id_typestring否用户 ID 类型
示例值：user_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - employee_id: 企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。 获取employee_id的方式： - 企业管理员在 管理后台 > 组织架构 > 成员与部门 页面，点击 成员详情，查询员工ID - 通过 批量获取员工列表 的接口，通过手机号或邮箱查询员工ID。
默认值：open_id
当值为 employee_id，字段权限要求： directory:employee.base.external_id:read 查看员工自定义 ID
department_id_typestring否此次调用中使用的部门ID的类型
示例值：department_id
可选值有：
- department_id: 用来标识租户内一个唯一的部门 - open_department_id: 用来在具体某个应用中标识一个部门，同一个部门 在不同应用中的 open_department_id 相同。
默认值：open_department_id

请求体 ​

名称类型必填描述
department_idsstring\[\]是部门ID，与department_id_type类型保持一致。id获取方式：可通过管理后台查询。
示例值：["adqwea"]
数据校验规则：
- 长度范围：1 ～ 100
required_fieldsstring\[\]是需要查询的字段列表。将按照传递的字段列表返回有权限的行、列数据。不传则不会返回任何字段了解更多：字段枚举说明
示例值：["name"]
数据校验规则：
- 长度范围：0 ～ 100

请求体示例 ​

json
{
    "department_ids": [
        "adqwea"
    ],
    "required_fields": [
        "name"
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ departmentsdepartment\[\]部门信息
    └ department_idstring部门ID，与department_id_type类型保持一致
字段权限要求（满足任一）： directory:department.base:read 查看部门基础信息 directory:department.external_id:read 查看部门自定义 ID
    └ department_countdepartment_count部门成员计数与子部门计数。计算结果可能会有延迟
字段权限要求（满足任一）： directory:department.count:read 查看部门成员与子部门计数 directory:department.organization:read 查看部门组织架构信息
      └ recursive_members_countstring递归成员数量
单位：个
      └ direct_members_countstring直属成员数量
单位：个
      └ recursive_members_count_exclude_leadersstring递归成员数量(不含leader)
单位：个
      └ recursive_departments_countstring递归子部门数量
单位：个
      └ direct_departments_countstring直属子部门数量
单位：个
    └ has_childboolean是否有子部门
字段权限要求（满足任一）： directory:department.has_child:read 查看部门是否有子部门 directory:department.organization:read 查看部门组织架构信息
    └ leadersdepartment_leader\[\]部门负责人
字段权限要求： directory:department.leader:read 查看部门负责人信息
      └ leader_typeint部门负责人类型
可选值有：
- 1: 主 - 2: 副
      └ leader_idstring部门负责人ID，与employee_id_type类型保持一致
    └ parent_department_idstring父部门ID，与department_id_type类型保持一致
字段权限要求（满足任一）： directory:department.organization:read 查看部门组织架构信息 directory:department.parent_id:read 查看部门的父部门 ID
    └ namei18n_text部门名称
字段权限要求（满足任一）： directory:department.base:read 查看部门基础信息 directory:department.name:read 查看部门的名称
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ enabled_statusboolean是否启用
字段权限要求： directory:department.status:read 查看部门的停启用状态
    └ order_weightstring部门排序权重
字段权限要求（满足任一）： directory:department.order_weight:read 查看部门排序权重 directory:department.organization:read 查看部门组织架构信息
    └ custom_field_valuescustom_field_value\[\]部门自定义字段值
字段权限要求： directory:department.custom_field:read 查看部门自定义字段信息
      └ field_typestring自定义字段类型
可选值有：
- 1: 多行文本 - 2: 网页链接 - 3: 枚举选项 - 4: 人员 - 9: 电话 - 10: 多选枚举类型(目前仅支持文本类型) - 11: 人员列表
      └ text_valuei18n_text文本字段值
        └ default_valuestring默认值
        └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
      └ url_valueurl_value网页链接字段值
        └ link_texti18n_text网页标题
          └ default_valuestring默认值
          └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
        └ urlstring移动端网页链接
        └ pcurlstring桌面端网页链接
      └ enum_valueenum_value枚举字段值
        └ enum_idsstring\[\]选项结果ID
        └ enum_typestring选项类型
可选值有：
- 1: 文本 - 2: 图片
      └ user_valuesuser_value\[\]人员字段值
        └ idsstring\[\]人员ID，与employee_id_type类型保持一致
      └ phone_valuephone_value电话字段值
        └ phone_numberstring电话号
        └ extension_numberstring分机号
      └ field_keystring自定义字段key
    └ department_path_infosdepartment_base_info\[\]部门路径信息。排列顺序为根级到末级，不包含根部门
字段权限要求： directory:department.department_path:read 查看部门路径信息
      └ department_idstring部门ID，与department_id_type类型保持一致
      └ department_namei18n_text部门名称
        └ default_valuestring默认值
        └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ data_sourceint数据来源
可选值有：
- 1: 管理后台 - 2: 人事企业版 - 3: SCIM
字段权限要求（满足任一）： directory:department.base:read 查看部门基础信息 directory:department.data_source:read 查看部门数据来源
  └ abnormalsabnormal_record\[\]字段异常信息
    └ idstring异常ID
    └ row_errorint行级异常
可选值有：
- 0: 成功 - 1000: 没权限
    └ field_errorsmap<string, int>列级异常，key为字段名,value为下列枚举 可选值有：
- 1000: 无权限 - 2000: 服务异常 - 2003: 字段不存在

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "departments": [
            {
                "department_id": "h12921",
                "department_count": {
                    "recursive_members_count": "100",
                    "direct_members_count": "100",
                    "recursive_members_count_exclude_leaders": "100",
                    "recursive_departments_count": "100",
                    "direct_departments_count": "100"
                },
                "has_child": true,
                "leaders": [
                    {
                        "leader_type": 1,
                        "leader_id": "u273y71"
                    }
                ],
                "parent_department_id": "h12921",
                "name": {
                    "default_value": "张三",
                    "i18n_value": {
                        "zh_cn": "中文",
                        "ja_jp": "ja_jp_name",
                        "en_us": "en_us_name"
                    }
                },
                "enabled_status": true,
                "order_weight": "无",
                "custom_field_values": [
                    {
                        "field_type": "1",
                        "text_value": {
                            "default_value": "张三",
                            "i18n_value": {
                                "zh_cn": "中文",
                                "ja_jp": "ja_jp_name",
                                "en_us": "en_us_name"
                            }
                        },
                        "url_value": {
                            "link_text": {
                                "default_value": "张三",
                                "i18n_value": {
                                    "zh_cn": "中文",
                                    "ja_jp": "ja_jp_name",
                                    "en_us": "en_us_name"
                                }
                            },
                            "url": "https://m.bytedance.com/afnasjfna",
                            "pcurl": "http://www.fs.cn"
                        },
                        "enum_value": {
                            "enum_ids": [
                                "1"
                            ],
                            "enum_type": "1"
                        },
                        "user_values": [
                            {
                                "ids": [
                                    "1"
                                ]
                            }
                        ],
                        "phone_value": {
                            "phone_number": "18812345678",
                            "extension_number": "234234234"
                        },
                        "field_key": "C-1000001"
                    }
                ],
                "department_path_infos": [
                    {
                        "department_id": "1",
                        "department_name": {
                            "default_value": "张三",
                            "i18n_value": {
                                "zh_cn": "中文",
                                "ja_jp": "ja_jp_name",
                                "en_us": "en_us_name"
                            }
                        }
                    }
                ],
                "data_source": 1
            }
        ],
        "abnormals": [
            {
                "id": "eedasfwe",
                "row_error": 0,
                "field_errors": {
                    "name": 1000
                }
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4002220001param is invalid无效的请求参数，请检查请求参数是否符合文档要求，或参考参数说明文档确认参数格式。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有