搜索部门

调用该接口以用户身份通过部门名称关键词查询可见部门的信息，包括部门的 ID、父部门、负责人以及状态等。

注意事项

该接口只能以用户身份（user_access_token）调用，搜索结果受用户身份的组织架构可见范围影响。如果部门不在当前用户的可见范围内，则无法被搜索到。用户的组织架构可见范围需要由企业管理员在管理后台 > 安全 > 成员权限 > 组织架构可见范围 内调整。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/departments/search
HTTP Method	POST
接口频率限制	特殊频控
支持的应用类型	custom,isv
权限要求调用该 API 所需的权限。开启其中任意一项权限即可调用开启任一权限即可	`contact:contact.base:readonly` 获取通讯录基本信息 `search:department:read` 搜索部门 `contact:contact:access_as_app` 以应用身份访问通讯录 `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	是	`user_access_token` 值格式："Bearer `access_token`" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

查询参数

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

请求体

名称	类型	必填	描述
`query`	`string`	是	搜索关键词，匹配字段为部门名称（不支持匹配部门国际化名称）。示例值："DemoName"

请求体示例

json

{
    "query": "DemoName"
}

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.NewSearchDepartmentReqBuilder().
		PageSize(20).
		Body(larkcontact.NewSearchDepartmentReqBodyBuilder().
			Query(`DemoName`).
			Build()).
		Build()

	// 发起请求
	resp, err := client.Contact.Department.Search(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.SearchDepartmentReq;
import com.lark.oapi.service.contact.v3.model.SearchDepartmentReqBody;
import com.lark.oapi.service.contact.v3.model.SearchDepartmentResp;

public class Main {

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

        // 创建请求对象
        SearchDepartmentReq req = SearchDepartmentReq.newBuilder()
                .pageSize(20)
                .searchDepartmentReqBody(SearchDepartmentReqBody.newBuilder()
                        .query("DemoName")
                        .build())
                .build();

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

响应

响应体

名称	类型	描述
`code`	`int`	错误码，非 0 表示失败
`msg`	`string`	错误描述
`data`	`\-`	-
└ `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` 以应用身份读取通讯录
└ `page_token`	`string`	分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
└ `has_more`	`boolean`	是否还有更多项

响应体示例

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
            }
        ],
        "page_token": "AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR",
        "has_more": true
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	48001	invalid param	参数错误，请检查请求参数填写是否有误。
500	48002	Internal Server Error	系统错误。先重试，如仍无法解决，请咨询技术支持。

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

事件

事件

事件

事件

事件

搜索部门

注意事项

请求

请求头

查询参数

请求体

请求体示例

响应

响应体

响应体示例

错误码

搜索部门 ​

注意事项 ​

请求 ​

请求头 ​

查询参数 ​

请求体 ​

请求体示例 ​

响应 ​

响应体 ​

响应体示例 ​

错误码 ​

搜索部门

注意事项

请求

请求头

查询参数

请求体

请求体示例

响应

响应体

响应体示例

错误码