# 搜索用户

通过用户名关键词搜索其他用户的信息，包括用户头像、用户名、用户所在部门、用户 user_id 以及 open_id。

## 注意事项

- 仅支持通过用户身份（user_access_token）调用该接口。
- 无法搜索到外部企业或已离职的用户。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/search/v1/user
HTTP Method | GET
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 搜索用户(contact:user:search)
字段权限要求<br>**接口返回的部分字段受权限控制，开启字段权限才可获取对应字段数据；如无需获取这些字段，则无需开启。**<br>根据要获取的字段开启相应权限 | 获取用户 user ID(contact:user.employee_id:readonly)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `user_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 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"

### 查询参数

名称 | 类型 | 必填 | 描述
---|---|---|---
query | string | 是 | 搜索关键词，接口通过传入的关键词搜索相匹配的用户名。
page_size | int | 否 | 分页大小，用于限制当前请求所返回的数据条目数。<br>- **最小值**：1<br>- **最大值**：200<br>- **默认值**：20
page_token | string | 否 | 分页标识，首次调用该接口时无需填写。如果返回值中包含了 page_token 值，则可以使用该值继续调用本接口，并将该值传入查询参数 page_token 中，以获取下一页数据。

## 响应
### 响应体

字段 | 数据类型 | 描述
---|---|---
code | int | 返回码，非 0 表示失败。
msg | string | 返回码对应的描述。例如返回 `ok` 表示成功。
data | \- | \-
has_more | boolean | 是否还有更多数据，当返回值为 true 时，表示存在下一页，即 page_token 不为空。
page_token | string | 分页标识，存在下一页（has_more 为 true）时会返回该值。下次请求带上此标识可以获取下一页的用户数据。
users | object | 搜索到的用户列表。
avatar | avatar_info | 用户的头像信息。<br>**注意**：为避免 URL 更新，头像 URL 不建议保存下来长期使用，推荐你在需要使用头像 URL 时再调用本接口进行获取。
avatar_72 | string | 用户的头像图片 URL，大小 72×72 px。
avatar_240 | string | 用户的头像图片 URL，大小 240×240 px。
avatar_640 | string | 用户的头像图片 URL，大小 640×640 px。
avatar_origin | string | 用户的头像图片 URL，原始大小。
department_ids | string[] | 用户所在的部门 ID 列表。
name | string | 用户名。
open_id | string | 用户的 open_id。open_id 是用户 ID 类型中的一种，详细介绍可参见[用户身份概述](https://open.feishu.cn/document/home/user-identity-introduction/introduction)。
user_id | string | 用户的 user_id。user_id 是用户 ID 类型中的一种，详细介绍可参见[用户身份概述](https://open.feishu.cn/document/home/user-identity-introduction/introduction)。<br>**说明**：只有已申请 [**获取用户 UserID**](https://open.feishu.cn/document/ukTMukTMukTM/uQjN3QjL0YzN04CN2cDN) API 权限的 **企业自建应用** 会返回该字段。

### 响应体示例
```json
{
    "code": 0,
    "msg": "ok",
    "data": {
        "has_more": true,
        "page_token": "20",
        "users": [
            {
                "avatar": {
                    "avatar_72": "https://example.com/static-resource/v1/d1ca00148ad2c2cf1111~72x72.png",
                    "avatar_240": "https://example.com/static-resource/v1/d1ca00148ad2c2cf1111~240x240.png",
                    "avatar_640": "https://example.com/static-resource/v1/d1ca00148ad2c2cf1111~640x640.png",
                    "avatar_origin": "https://example.com/static-resource/v1/d1ca00148ad2c2cf1111~noop.png"
                },
                "department_ids": [
                    "od-c02cc3b682a71cdb3a4f14fc4cdb1234"
                ],
                "name": "zhangsan",
                "open_id": "ou_7d8a6e6df7621556ce0d21922b674321",
                "user_id": "02a11111"
            }
        ]
    }
}
```
### 错误码

更多错误码信息，参见[通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)。