飞书开放平台 Server API 文档

主题

获取部门信息列表 ​

该接口用于获取当前部门子部门列表。常见问题答疑。

Warning: 本接口为历史版本接口，不再维护。推荐接口：

Tip: - 使用 user_access_token 时，返回该用户组织架构可见性范围（登陆企业管理后台进行权限配置）内的所有可见部门。当进行递归查询时，只筛查最多1000个部门的可见性。

  • 使用 tenant_access_token 则基于应用的通讯录权限范围进行权限校验与过滤。由于 parent_department_id 是非必填参数，填与不填存在两种数据权限校验与返回情况： 1、请求设置了 parent_department_id 为A（根部门0），会检验A是否在通讯录权限内，若在( parent_department_id=0 时会校验是否为全员权限），则返回部门下子部门列表（根据fetch_child决定是否递归），否则返回无部门通讯录权限错误码。 2、请求未带 parent_department_id 参数，如通讯录范围为全员权限，只返回根部门ID(部门ID为0)，否则返回根据通讯录范围配置的部门ID及子部门(根据 fetch_child 决定是否递归)。

请求 ​

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

请求头 ​

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

查询参数 ​

名称类型必填描述
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
department_id_typestring否此次调用中使用的部门ID的类型
示例值："open_department_id"
可选值有：
- department_id: 以自定义department_id来标识部门 - open_department_id: 以open_department_id来标识部门
默认值：open_department_id
parent_department_idstring否父部门的ID，填上获取部门下所有子部门，此处填写的 ID 必须是 department_id_type 指定的 ID。
示例值："od-4e6ac4d14bcd5071a37a39de902c7141"
fetch_childboolean否是否递归获取子部门
示例值：是否递归获取子部门，默认值：false
page_sizeint否分页大小
示例值：10
默认值：10
数据校验规则： - 最大值：50
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值："AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR"

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ has_moreboolean是否还有更多项
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ itemsdepartment\[\]
    └ namestring部门名称。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
    └ i18n_namedepartment_i18n_name国际化的部门名称。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
      └ zh_cnstring部门的中文名。
      └ ja_jpstring部门的日文名。
      └ en_usstring部门的英文名。
    └ parent_department_idstring父部门的 ID。取值为 0 表示当前部门的父部门为根部门。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
    └ department_idstring当前部门的自定义部门 ID。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
    └ open_department_idstring部门的 open_department_id。
    └ leader_user_idstring部门主管的 open_id。关于用户 ID 的说明可参见 用户相关的 ID 概念。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
    └ chat_idstring部门群 ID。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
    └ orderstring部门的排序，即部门在其同级部门的展示顺序。取值越小排序越靠前。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
    └ unit_idsstring\[\]部门单位的自定义 ID 列表。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
    └ member_countint部门下用户的个数。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
    └ statusdepartment_status部门状态。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
      └ is_deletedboolean是否被删除。
可能值：
- true：是 - false：否
    └ leadersdepartmentLeader\[\]部门负责人信息。
      └ leaderTypeint负责人类型。
可选值有：
- 1: 主负责人。 - 2: 副负责人。
      └ leaderIDstring负责人的用户 open_id。了解用户 ID 可参见用户相关的 ID 概念。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录
    └ group_chat_employee_typesint\[\]部门群雇员类型限制。当该字段列表为空时，表示为无任何雇员类型。类型字段可包含以下值：
- 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问 - 6：其他自定义类型字段。你可以调用获取人员类型接口，获取到该租户的自定义员工类型的名称。
    └ department_hrbpsstring\[\]部门HRBP
字段权限要求： contact:department.hrbp:readonly 查询部门 HRBP 信息
    └ primary_member_countint部门下主属用户的个数。
字段权限要求（满足任一）： contact:contact:readonly_as_app 以应用身份读取通讯录 contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "has_more": true,
        "page_token": "AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR",
        "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,2,3
                ],
                "department_hrbps": [
                    "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                ],
                "primary_member_count": 100
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
40043010big dept forbid recursion error超大部门不允许进行查询。
40040003internal error内部错误，请提供 X-Request-Id向客服反馈。联系客服。
40040008dept Info is null error部门的信息不能为空
40340014no parent dept authority error没有父部门权限（组织架构可见范围权限）。
40040011page size is invalid无效的分页参数
40040012page token is invalid errorpage token无效。
40142008tenant id is invalid error请检查请求租户是否为合法租户。
40043007duplicated department custom id error部门自定义ID 企业内重复
40340004no dept authority error操作的部门需在通讯录权限范围中，了解更多

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

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