# 搜索部门 本接口用于搜索部门信息，通过部门名称等关键词搜索部门信息，返回符合条件的部门列表。 **注意事项**：注意： - 本接口支持tenant_access_token和user_access_token。 - 使用tenant_access_token时，数据权限遵循应用的通讯录权限范围，返回的字段数据为应用有权限的字段。**考虑到数据安全仅返回最多前100条匹配项**，若需精准结果需要更准确的输入。 - 使用user_access_token时，默认为管理员用户，将校验管理员管理范围。当用户有多个管理员身份均可查看员工信息时，管理员管理范围取最大集。 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/directory/v1/departments/search HTTP Method | POST 接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 搜索部门(directory:department:search) 字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
查看部门基础信息(directory:department.base:read)
查看部门成员与子部门计数(directory:department.count:read)
查看部门自定义字段信息(directory:department.custom_field:read)
查看部门数据来源(directory:department.data_source:read)
查看部门路径信息(directory:department.department_path:read)
查看部门自定义 ID(directory:department.external_id:read)
查看部门是否有子部门(directory:department.has_child:read)
查看部门负责人信息(directory:department.leader:read)
查看部门的名称(directory:department.name:read)
查看部门排序权重(directory:department.order_weight:read)
查看部门组织架构信息(directory:department.organization:read)
查看部门的父部门 ID(directory:department.parent_id:read)
查看部门的停启用状态(directory:department.status:read)
查看员工自定义 ID(directory:employee.base.external_id:read) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) Content-Type | string | 是 | **固定值**："application/json; charset=utf-8" ### 查询参数 名称 | 类型 | 必填 | 描述 ---|---|---|--- employee_id_type | string | 否 | 用户 ID 类型
**示例值**：open_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- employee_id：企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。
获取employee_id的方式：
- 企业管理员在 管理后台 > 组织架构 > 成员与部门 页面，点击 成员详情，查询员工ID
- 通过 [批量获取员工列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/directory-v1/employee/filter) 的接口，通过手机号或邮箱查询员工ID。
**默认值**：`open_id`
**当值为 `employee_id`，字段权限要求**：
查看员工自定义 ID(directory:employee.base.external_id:read) department_id_type | string | 否 | 此次调用中使用的部门ID的类型
**示例值**：open_department_id
**可选值有**：
- open_department_id：用来在具体某个应用中标识一个部门，同一个部门 在不同应用中的 open_department_id 不相同。
- department_id：用来标识租户内一个唯一的部门
**默认值**：`open_department_id` ### 请求体 名称 | 类型 | 必填 | 描述 ---|---|---|--- query | string | 是 | 搜索关键词。支持部门名称的搜索，最多可输入 100 字。
**示例值**："zhang" page_request | page_condition | 是 | 分页信息 page_size | int | 否 | 本次请求条数，最大100条
**默认值**：20
**最小值**：0
**示例值**：100 page_token | string | 否 | 顺序分页查询，不能跳页查询，支持深分页，在需要遍历全部数据的场景只能使用该方式。第一次传空字符串或者不传，后面传上一次的返回值中的page_token
**示例值**："xdcftvygbuhijhgrexr" required_fields | string\[\] | 是 | 需要查询的字段列表。将按照传递的字段列表返回有权限的行、列数据。不传则不会返回任何字段
[了解更多：字段枚举说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/directory-v1/field-enumeration)
**示例值**：["name"]
**数据校验规则**：
- 长度范围：`0` ～ `100` ### 请求体示例 ```json { "query": "zhang", "page_request": { "page_size": 100, "page_token": "xdcftvygbuhijhgrexr" }, "required_fields": [ "name" ] } ``` ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- departments | department\[\] | 部门信息 department_id | string | 部门ID，与department_id_type类型保持一致
**字段权限要求（满足任一）**：
查看部门基础信息(directory:department.base:read)
查看部门自定义 ID(directory:department.external_id:read) department_count | department_count | 部门成员计数与子部门计数。计算结果可能会有延迟
**字段权限要求（满足任一）**：
查看部门成员与子部门计数(directory:department.count:read)
查看部门组织架构信息(directory:department.organization:read) recursive_members_count | string | 递归成员数量 direct_members_count | string | 直属成员数量 recursive_members_count_exclude_leaders | string | 递归成员数量(不含leader) recursive_departments_count | string | 递归子部门数量 direct_departments_count | string | 直属子部门数量 has_child | boolean | 是否有子部门
**字段权限要求（满足任一）**：
查看部门是否有子部门(directory:department.has_child:read)
查看部门组织架构信息(directory:department.organization:read) leaders | department_leader\[\] | 部门负责人
**字段权限要求**：
查看部门负责人信息(directory:department.leader:read) leader_type | int | 部门负责人类型
**可选值有**：
- 1：主
- 2：副 leader_id | string | 部门负责人ID，与employee_id_type类型保持一致 parent_department_id | string | 父部门ID
**字段权限要求（满足任一）**：
查看部门组织架构信息(directory:department.organization:read)
查看部门的父部门 ID(directory:department.parent_id:read) name | i18n_text | 部门名称
**字段权限要求（满足任一）**：
查看部门基础信息(directory:department.base:read)
查看部门的名称(directory:department.name:read) default_value | string | 默认值 i18n_value | map<string, string> | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值 enabled_status | boolean | 是否启用
**字段权限要求**：
查看部门的停启用状态(directory:department.status:read) order_weight | string | 部门排序权重
**字段权限要求（满足任一）**：
查看部门排序权重(directory:department.order_weight:read)
查看部门组织架构信息(directory:department.organization:read) custom_field_values | custom_field_value\[\] | 部门自定义字段值
**字段权限要求**：
查看部门自定义字段信息(directory:department.custom_field:read) field_type | string | 自定义字段类型
**可选值有**：
- 1：多行文本
- 2：网页链接
- 3：枚举选项
- 4：人员
- 9：电话
- 10：多选枚举类型(目前仅支持文本类型)
- 11：人员列表 text_value | i18n_text | 文本字段值 default_value | string | 默认值 i18n_value | map<string, string> | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值 url_value | url_value | 网页链接字段值 link_text | i18n_text | 网页标题 default_value | string | 默认值 i18n_value | map<string, string> | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值 url | string | 移动端网页链接 pcurl | string | 桌面端网页链接 enum_value | enum_value | 枚举字段值 enum_ids | string\[\] | 选项结果ID enum_type | string | 选项类型
**可选值有**：
- 1：文本
- 2：图片 user_values | user_value\[\] | 人员字段值 ids | string\[\] | 人员ID，与employee_id_type类型保持一致 phone_value | phone_value | 电话字段值 phone_number | string | 电话号 extension_number | string | 分机号 field_key | string | 自定义字段key department_path_infos | department_base_info\[\] | 部门路径信息。排列顺序为根级到末级，不包含根部门
**字段权限要求**：
查看部门路径信息(directory:department.department_path:read) department_id | string | 部门ID，与department_id_type类型保持一致 department_name | i18n_text | 部门名称 default_value | string | 默认值 i18n_value | map<string, string> | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值 data_source | int | 数据来源
**可选值有**：
- 1：管理后台
- 2：人事企业版
- 3：SCIM
**字段权限要求（满足任一）**：
查看部门基础信息(directory:department.base:read)
查看部门数据来源(directory:department.data_source:read) page_response | page_response | 分页结果 has_more | boolean | 是否还有后续结果，如果has_more为true，代表还有数据没有完全返回，需要使用响应结果中的page_token，并再次请求才能取得剩下的数据。 page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token abnormals | abnormal_record\[\] | 字段异常信息 id | string | 异常ID row_error | int | 行级异常
**可选值有**：
- 0：成功
- 1000：没权限 field_errors | map<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": "3000", "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 } ], "page_response": { "has_more": true, "page_token": "aihsdniandafoafa" }, "abnormals": [ { "id": "eedasfwe", "row_error": 0, "field_errors": { "name": "1000" } } ] } } ``` ### 错误码 HTTP状态码 | 错误码 | 描述 | 排查建议 ---|---|---|--- 400 | 2220001 | param is invalid | 无效的请求参数 400 | 2221004 | invalid page token | 无效的分页token，请检查分页token是否正确，或重新获取有效的page_token。 400 | 2221005 | no page request | 无分页参数，请添加有效的分页参数（page_request）。 400 | 2220010 | Exceeded the limit size | 不支持offset分页方式，超过了限制大小，不支持offset分页方式，请使用page_token分页方式。