获取子部门列表

调用该接口查询指定部门下的子部门列表，列表内包含部门的名称、ID、父部门、负责人以及状态等信息。

注意事项

当你使用应用身份（tenant_access_token）调用本接口时，应用的通讯录权限范围内需要包含当前被查询的部门。如果需要查询根部门（部门 ID 为 0）下的子部门列表，则应用的通讯录权限范围需设置为 全部成员。了解权限范围参见权限范围资源介绍。
当你使用用户身份（user_access_token）调用本接口时需要注意：
- 确保该用户身份拥有待查询部门的可见性，用户的组织架构可见范围需要由企业管理员在管理后台 > 安全 > 成员权限 > 组织架构可见范围 内调整。
- 请求时如果开启了递归获取子部门（fetch_child 取值为 true），则用户可查询到的部门数量上限为 1000 个。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/departments/:department_id/children
HTTP Method	GET
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求调用该 API 所需的权限。开启其中任意一项权限即可调用开启任一权限即可	`contact:contact.base:readonly` 获取通讯录基本信息 `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
字段权限要求	> 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` 以应用身份读取通讯录

请求头

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

路径参数

名称	类型	描述
`department_id`	`string`	部门 ID。说明： - ID 类型需要与查询参数 department_id_type 的取值保持一致。 - 当你在创建部门时，可从返回结果中获取到部门 ID 信息，你也可以调用搜索部门接口，获取所需的部门 ID。 - 根部门的部门 ID 为 0。示例值："D096" 数据校验规则： - 最大长度：`64` 字符 - 正则校验：`^[a-zA-Z0-9][a-zA-Z0-9_\-@.]{0,63}$`

查询参数

名称	类型	必填	描述
`user_id_type`	`string`	否	用户 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_type`	`string`	否	此次调用中的部门 ID 类型。关于部门 ID 的详细介绍，可参见部门 ID 说明。示例值：open_department_id 可选值有： - `department_id`: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。 - `open_department_id`: 由系统自动生成的部门 ID，ID 前缀固定为 `od-`，在租户内全局唯一。默认值：`open_department_id`
`fetch_child`	`boolean`	否	是否递归获取子部门。取值为 true 时，接口会递归查询当前部门下所有层级的子部门信息。可选值有： - true：是 - false（默认值）：否示例值：false
`page_size`	`int`	否	分页大小，用于限制一次请求所返回的数据条目数。示例值：10 默认值：`10` 数据校验规则： - 最大值：`50`
`page_token`	`string`	否	分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果示例值：AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ+G8JG6tK7+ZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR

Go 请求示例

import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewChildrenDepartmentReqBuilder().
		DepartmentId(`D096`).
		PageSize(10).
		Build()

	// 发起请求
	resp, err := client.Contact.Department.Children(context.Background(), req)
}

Java 请求示例

java

import com.lark.oapi.Client;
import com.lark.oapi.core.request.RequestOptions;
import com.lark.oapi.service.contact.v3.model.ChildrenDepartmentReq;
import com.lark.oapi.service.contact.v3.model.ChildrenDepartmentResp;

public class Main {

    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        ChildrenDepartmentReq req = ChildrenDepartmentReq.newBuilder()
                .departmentId("D096")
                .pageSize(10)
                .build();

        // 发起请求
        ChildrenDepartmentResp resp = client.contact().department().children(req, RequestOptions.newBuilder().build());
    }
}

响应

响应体

名称	类型	描述
`code`	`int`	错误码，非 0 表示失败
`msg`	`string`	错误描述
`data`	`\-`	-
└ `has_more`	`boolean`	是否还有更多项
└ `page_token`	`string`	分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
└ `items`	`department\[\]`	部门列表。
└ `name`	`string`	部门名称。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `i18n_name`	`department_i18n_name`	部门名称的国际化配置。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `zh_cn`	`string`	部门的中文名。
└ `ja_jp`	`string`	部门的日文名。
└ `en_us`	`string`	部门的英文名。
└ `parent_department_id`	`string`	父部门的部门 ID。 - ID 类型与查询参数的 department_id_type 取值保持一致。 - 当父部门为根部门时，该参数值为 `0`。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `department_id`	`string`	自定义部门 ID。后续可以使用该 ID 删除、修改、查询部门信息。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `open_department_id`	`string`	部门的 open_department_id，由系统自动生成。后续可以使用该 ID 删除、修改、查询部门信息。
└ `leader_user_id`	`string`	部门主管的用户 ID，ID 类型与查询参数的 user_id_type 取值保持一致。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `chat_id`	`string`	部门群的群 ID。后续可以使用获取群信息，获取群的详细信息。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `order`	`string`	部门的排序，即部门在其同级部门的展示顺序。取值越小排序越靠前。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `unit_ids`	`string\[\]`	部门绑定的单位自定义 ID 列表，当前只支持一个。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `member_count`	`int`	当前部门及其下属部门的用户（包含部门负责人）个数。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `status`	`department_status`	部门状态。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `is_deleted`	`boolean`	是否被删除。可能值有： - true：是 - false：否
└ `leaders`	`departmentLeader\[\]`	部门负责人信息。
└ `leaderType`	`int`	负责人类型。可选值有： - `1`: 主负责人 - `2`: 副负责人
└ `leaderID`	`string`	负责人的用户 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_types`	`int\[\]`	部门群的人员类型限制。人员类型的可能值如下： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问如果是自定义人员类型，则会返回对应的编号。你可以调用查询人员类型接口，获取相应编号（enum_value）对应的自定义人员类型信息。
└ `department_hrbps`	`string\[\]`	部门 HRBP 的用户 ID 列表。 ID 类型与查询参数 user_id_type 的取值保持一致。字段权限要求： `contact:department.hrbp:readonly` 查询部门 HRBP 信息
└ `primary_member_count`	`int`	当前部门及其下属部门的主属成员（即成员的主部门为当前部门）的数量。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录

响应体示例

json

{
    "code":0,
    "msg":"success",
    "data":{
        "has_more":true,
        "page_token":"AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ+G8JG6tK7+ZnHiT7COhD2hMSICh/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"
                    }
                ],
                "department_hrbps":[
                    "ou_10430f87894fce18e57891c48995cd7c"
                ]
            }
        ]
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	43010	big dept forbid recursion error	超大部门不允许进行查询。
400	40003	internal error	内部错误，请获取请求的 X-Request-Id，并向技术支持进行反馈。
400	40008	dept Info is null error	部门的信息不能为空。
403	40014	no parent dept authority error	没有父部门权限（组织架构可见范围权限）。
400	40011	page size is invalid	Page size 无效。你可以参考接口文档提供的 page_size 参数描述，修改为正确的取值后重试。
400	40012	page token is invalid error	Page token 无效。你需要检查传入的 page_token 是否为上次请求返回的 page_token 值。
401	42008	tenant id is invalid error	租户身份无效。请求时，请确保设置的请求头 Authorization 与待操作资源同属一个租户下。
400	43007	duplicated department custom id error	部门自定义 ID 企业内重复。
403	40004	no dept authority error	当前操作涉及的部门，需在应用通讯录权限范围中，了解更多可参见权限范围资源介绍。

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

事件

事件

事件

事件

事件

获取子部门列表

注意事项

请求

请求头

路径参数

查询参数

响应

响应体

响应体示例

错误码

获取子部门列表 ​

注意事项 ​

请求 ​

请求头 ​

路径参数 ​

查询参数 ​

响应 ​

响应体 ​

响应体示例 ​

错误码 ​

获取子部门列表

注意事项

请求

请求头

路径参数

查询参数

响应

响应体

响应体示例

错误码