飞书开放平台 Server API 文档

主题

批量获取部门信息 ​

调用该接口获取一个或多个部门的信息，包括部门名称、ID、父部门、负责人、状态以及成员个数等。

注意事项 ​

使用不同身份调用本接口时，需要注意不同身份所需的不同权限范围。具体说明如下：

  • 当你使用应用身份（tenant_access_token）调用本接口时，应用的通讯录权限范围内需要包含当前被查询的部门。如果需要查询根部门信息，则应用的通讯录权限范围需设置为 全部成员。了解权限范围参见权限范围资源介绍。
  • 当你使用用户身份（user_access_token）调用本接口时，需要确保该用户身份拥有待查询部门的可见性。如果需要查询根部门信息，则用户需要可见所有人。用户的组织架构可见范围需要由企业管理员在管理后台 > 安全 > 成员权限 > 组织架构可见范围 内调整。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/contact/v3/departments/batch
HTTP MethodGET
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用contact:contact.base:readonly 获取通讯录基本信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:department.base:readonly 获取部门基础信息 contact:user.employee_id:readonly 获取用户 user ID contact:department.hrbp:readonly 查询部门 HRBP 信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

查询参数 ​

名称类型必填描述
department_idsstring\[\]是部门 ID，ID 类型需要与查询参数 department_id_type 的取值保持一致。ID 获取方式说明：
- 调用创建部门接口后，可从返回结果中获取到部门 ID 信息。 - 部门 API 提供了多种获取其他部门 ID 的方式，如获取子部门列表、获取父部门信息、搜索部门，你可以选择合适的 API 进行查询。
注意：
- 单次最大请求的 ID 数量为 50。 - 如需一次查询多个部门，可将同一参数名多次传递，并且每次传递不同的部门 ID 进行查询。GET 请求示例： https://{url}?department_ids={department_id1}&department_ids={department_id2}。其中： - department_ids 是参数名，可以多次传递。 - department_id1和department_id2是不同的参数值。
示例值：D096
department_id_typestring否此次调用中的部门 ID 类型。关于部门 ID 的详细介绍，可参见部门 ID 说明。
示例值：open_department_id
可选值有：
- open_department_id: 由系统自动生成的部门 ID，ID 前缀固定为 od-，在租户内全局唯一。 - department_id: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。
默认值：open_department_id
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemsdepartment\[\]查询到的部门信息。
说明：多个部门 ID 中的异常部门 ID 不会返回结果。
    └ namestring部门名称。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ i18n_namedepartment_i18n_name部门名称的国际化配置。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
      └ zh_cnstring部门的中文名。
      └ ja_jpstring部门的日文名。
      └ en_usstring部门的英文名。
    └ parent_department_idstring父部门的部门 ID。
- ID 类型与查询参数的 department_id_type 取值保持一致。 - 当父部门为根部门时，该参数值为 0。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ department_idstring自定义部门 ID。后续可以使用该 ID 删除、修改、查询部门信息。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ open_department_idstring部门的 open_department_id，由系统自动生成。后续可以使用该 ID 删除、修改、查询部门信息。
    └ leader_user_idstring部门主管的用户 ID，ID 类型与查询参数的 user_id_type 取值保持一致。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ chat_idstring部门群的群 ID。后续可以使用获取群信息，获取群的详细信息。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ orderstring部门的排序，即部门在其同级部门的展示顺序。取值越小排序越靠前。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ unit_idsstring\[\]部门绑定的单位自定义 ID 列表，当前只支持一个。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ member_countint当前部门及其下属部门的用户（包含部门负责人）个数。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ statusdepartment_status部门状态。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
      └ is_deletedboolean是否被删除。
可能值有：
- true：是 - false：否
    └ leadersdepartmentLeader\[\]部门负责人信息。
      └ leaderTypeint负责人类型。
可选值有：
- 1: 主负责人 - 2: 副负责人
      └ leaderIDstring负责人的用户 ID，ID 类型与查询参数的 user_id_type 取值保持一致。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ group_chat_employee_typesint\[\]部门群的人员类型限制。人员类型的可能值如下：
- 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问
如果是自定义人员类型，则会返回对应的编号。你可以调用查询人员类型接口，获取相应编号（enum_value）对应的自定义人员类型信息。
    └ department_hrbpsstring\[\]部门 HRBP 的用户 ID 列表。 ID 类型与查询参数 user_id_type 的取值保持一致。
字段权限要求： contact:department.hrbp:readonly 查询部门 HRBP 信息
    └ primary_member_countint当前部门及其下属部门的主属成员（即成员的主部门为当前部门）的数量。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "name": "DemoName",
                "i18n_name": {
                    "zh_cn": "Demo名称",
                    "ja_jp": "デモ名",
                    "en_us": "Demo Name"
                },
                "parent_department_id": "D067",
                "department_id": "D096",
                "open_department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "chat_id": "oc_5ad11d72b830411d72b836c20",
                "order": "100",
                "unit_ids": [
                    "custom_unit_id"
                ],
                "member_count": 100,
                "status": {
                    "is_deleted": false
                },
                "leaders": [
                    {
                        "leaderType": 1,
                        "leaderID": "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                    }
                ],
                "group_chat_employee_types": [
                    1
                ],
                "department_hrbps": [
                    "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                ],
                "primary_member_count": 100
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
40040001param is invalid参数错误。请检查请求时输出参数是否填写有误。
40043010big dept forbid recursion error超大部门不允许进行查询。
40040003internal error内部错误，请获取请求的 X-Request-Id，并向技术支持进行反馈。
40040008dept Info is null error部门的信息不能为空。
40340014no parent dept authority error操作部门的父部门需在通讯录权限范围中，了解更多。
40040011page size is more than 50 errorpage_size 参数超过 50，请减少数量后重试。
40040012page token is invalid error非法的 page_token 参数，请从结果中获取 page_token 后重试。
40142008tenant id is invalid error租户身份无效。请求时，请求头 Authorization 对应的租户身份，需要是当前操作中的资源的所属租户。
40043007duplicated department unit custom id error部门 unit 的自定义 ID 重复，请检查数据后重试。
40340004no dept authority error当前操作涉及的部门，需在应用通讯录权限范围中，了解更多可参见权限范围资源介绍。

更多错误码信息，参见通用错误码。

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

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