服务端 API/通讯录/用户/通过手机号或邮箱获取用户 ID # 通过手机号或邮箱获取用户 ID 通过该接口，可使用手机号/邮箱获取用户的 ID 信息，具体获取支持的 ID 类型包括 open_id、user_id、union_id，可通过查询参数指定。 **注意事项**：不返回用户 ID 的情况说明： - 查询的手机号或者邮箱不存在。 - 未开通 **获取用户 user ID** 权限，将无法返回用户的 user_id。 - 无权限查看用户信息。你可以在开发者后台应用详情页的 **权限管理 > 数据权限 > 通讯录权限范围** 中，指定用户权限范围。 - 使用企业邮箱查询将无法返回用户 ID，需要使用用户的邮箱地址。 - 在请求头 Authorization 中，传入的 Token 有误。例如，Token 对应的应用与实际所需应用不一致。 - 所查询的用户已离职。 ## 请求 基本 |   ---|--- HTTP URL | https://open.larksuite.com/open-apis/contact/v3/users/batch_get_id HTTP Method | POST 接口频率限制 | [1000 次/分钟、50 次/秒](https://open.larksuite.com/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 通过手机号或邮箱获取用户 ID(contact:user.id:readonly) 字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户受雇信息(contact:user.employee:readonly)
获取用户 user ID(contact:user.employee_id:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly)
以应用身份读取通讯录(contact:contact:readonly_as_app) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) Content-Type | string | 是 | **固定值**："application/json; charset=utf-8" ### 查询参数 名称 | 类型 | 必填 | 描述 ---|---|---|--- user_id_type | string | 否 | 用户 ID 类型
**示例值**：user_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)
**默认值**：`open_id`
**当值为 `user_id`，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly) ### 请求体 名称 | 类型 | 必填 | 描述 ---|---|---|--- emails | string\[\] | 否 | 要查询的用户邮箱（不支持企业邮箱），最多 50 条。
注意，emails与mobiles相互独立，每条用户邮箱返回对应的用户ID。
本接口返回的用户ID数量为emails数量与mobiles数量的和。
**示例值**：["abc@z.com"]
**数据校验规则**：
- 最大长度：`50` mobiles | string\[\] | 否 | 要查询的用户手机号，最多 50 条。
注意
1. emails与mobiles相互独立，每条用户手机号返回对应的用户ID。
2. 非中国大陆地区的手机号需要添加以 “+” 开头的国家 / 地区代码。
**示例值**：["13812345678"]
**数据校验规则**：
- 最大长度：`50` include_resigned | boolean | 否 | 查询结果是否包含离职员工。取值为 true 后可查询离职用户的 ID
**示例值**：true
**默认值**：`false` ### 请求体示例 ```json { "emails": [ "zhangsan@z.com","lisi@a.com" ], "mobiles": [ "13812345678","13812345679" ], "include_resigned":true } ``` **Go 请求示例** ```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.NewBatchGetIdUserReqBuilder(). UserIdType(`open_id`). Body(larkcontact.NewBatchGetIdUserReqBodyBuilder(). Emails([]string{`zhangsan@z.com`, `lisi@a.com`}). Mobiles([]string{`13812345678`, `13812345679`}). Build()). Build() // 发起请求 resp, err := client.Contact.User.BatchGetId(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.BatchGetIdUserReq; import com.lark.oapi.service.contact.v3.model.BatchGetIdUserReqBody; import com.lark.oapi.service.contact.v3.model.BatchGetIdUserResp; public class Main { public static void main(String arg[]) throws Exception { // 构建client Client client = Client.newBuilder("appId", "appSecret").build(); // 创建请求对象 BatchGetIdUserReq req = BatchGetIdUserReq.newBuilder() .userIdType("open_id") .batchGetIdUserReqBody(BatchGetIdUserReqBody.newBuilder() .emails(new String[]{"zhangsan@z.com", "lisi@a.com"}) .mobiles(new String[]{"13812345678", "13812345679"}) .build()) .build(); // 发起请求 BatchGetIdUserResp resp = client.contact().user().batchGetId(req, RequestOptions.newBuilder().build()); } } ``` ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- user_list | user_contact_info\[\] | 手机号或者邮箱对应的用户id信息 user_id | string | 用户id，值为user_id_type所指定的类型。如果查询的手机号、邮箱不存在，或者无权限查看对应的用户，则不返回此项。 mobile | string | 手机号，通过手机号查询时返回 email | string | 邮箱，通过邮箱查询时返回 status | user_status | 用户状态
**字段权限要求（满足任一）**：
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly)
以应用身份读取通讯录(contact:contact:readonly_as_app) is_frozen | boolean | 是否冻结 is_resigned | boolean | 是否离职 is_activated | boolean | 是否激活 is_exited | boolean | 是否主动退出，主动退出一段时间后用户会自动转为已离职 is_unjoin | boolean | 是否未加入，需要用户自主确认才能加入团队 ### 响应体示例 ```json { "code": 0, "msg": "success", "data": { "user_list": [{ "user_id": "ou_979112345678741d29069abcdef089d4", "email": "zhanxxxxx@a.com", "status": { "is_frozen": false, "is_resigned": false, "is_activated": true, "is_exited": false, "is_unjoin": false } }, { "user_id": "ou_919112245678741d29069abcdef096af", "email": "lisixxxx@a.com", "status": { "is_frozen": false, "is_resigned": false, "is_activated": true, "is_exited": false, "is_unjoin": false } }, { "user_id": "ou_46a087654321a1dc920ffab8fedc823f", "mobile": "13xxxxxx678", "status": { "is_frozen": false, "is_resigned": false, "is_activated": true, "is_exited": false, "is_unjoin": false } }, { "user_id": "ou_01b081675121a1dc920ffab97cdc017a", "mobile": "138xxxxxx79", "status": { "is_frozen": false, "is_resigned": false, "is_activated": true, "is_exited": false, "is_unjoin": false } } ] } } ```