通过手机号或邮箱获取用户 ID

调用该接口通过手机号或邮箱获取一个或多个用户的 ID （包括 user_id、open_id、union_id）与状态信息。

注意事项

请求后不返回用户 ID 的可能原因：

• 请求头 Authorization 传入的 tenant_access_token 有误。例如，tenant_access_token 对应的应用与实际所需应用不一致。
• 输入的手机号或者邮箱不存在。
• 应用未开通 获取用户 user ID API 权限。
• 应用无权限查看用户信息。你需要在应用详情页为应用配置数据权限，具体说明参见配置应用数据权限。
• 使用企业邮箱查询将无法返回用户 ID，必须使用用户的邮箱地址。
• 所查询的用户已离职，如果请求参数 include_resigned 取值为 false，则不会返回离职用户 ID。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/users/batch_get_id
HTTP Method	POST
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	contact:user.id:readonly 通过手机号或邮箱获取用户 ID
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee:readonly 获取用户受雇信息 contact:user.employee_id:readonly 获取用户 user ID 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
Content-Type	string	是	固定值："application/json; charset=utf-8"

查询参数

名称	类型	必填	描述
user_id_type	string	否	用户 ID 类型 示例值：user_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

请求体

名称	类型	必填	描述
emails	string\[\]	否	要查询的用户邮箱，最多可传入 50 条。 注意： - 不支持企业邮箱。 - emails 与 mobiles 两个参数相互独立，即每个用户邮箱会返回对应的用户信息，每个手机号也会返回对应的用户信息。 - 本接口返回的用户 ID 数量为 emails 数量与 mobiles 数量之和。 默认值：空 示例值：["zhangsan@z.com"] 数据校验规则： - 最大长度：50
mobiles	string\[\]	否	要查询的用户手机号，最多可传入 50 条。 注意： - 非中国大陆地区的手机号需要添加以 “+” 开头的国家或地区代码。 - emails 与 mobiles 两个参数相互独立，即每个用户邮箱会返回对应的用户信息，每个手机号也会返回对应的用户信息。 - 本接口返回的用户 ID 数量为 emails 数量与 mobiles 数量之和。 默认值：空 示例值：["13011111111"] 数据校验规则： - 最大长度：50
include_resigned	boolean	否	查询结果是否包含离职员工的用户信息。 可选值有： - true：包含 - false：不包含 示例值：true 默认值：false

请求体示例

{
    "emails": [
"zhangsan@z.com","lisi@a.com"
    ],
    "mobiles": [
"13011111111","13022222222"
    ],
"include_resigned":true
}

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 请求示例

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，ID 类型与查询参数 user_id_type 的取值保持一致。 例如，user_id_type 取值为 open_id，则该参数的用户 ID 值为用户的 open_id。 不同用户 ID 的说明参见 用户相关的 ID 概念。
└ mobile	string	手机号，通过手机号查询时会返回该值。
└ email	string	邮箱，通过邮箱查询时会返回该值。
└ status	user_status	用户状态。通过 is_frozen、is_resigned、is_activated、is_exited 布尔值类型参数进行展示。 用户状态的流转逻辑可参见用户资源介绍。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ is_frozen	boolean	是否为冻结状态。 可能值有： - true：是 - false：否
└ is_resigned	boolean	是否为离职状态。 可能值有： - true：是 - false：否
└ is_activated	boolean	是否为激活状态。 可能值有： - true：是 - false：否
└ is_exited	boolean	是否为主动退出状态。主动退出一段时间后用户状态会自动转为已离职。 可能值有： - true：是 - false：否
└ is_unjoin	boolean	是否为未加入状态，需要用户自主确认才能加入企业或团队。 可能值有： - true：是 - false：否

响应体示例

{
	"code": 0,
	"msg": "success",
	"data": {
		"user_list": [{
				"user_id": "ou_979112345678741d29069abcdef01234",
				"email": "zhanxxxxx@a.com",
				"status": {
					"is_frozen": false,
					"is_resigned": false,
					"is_activated": true,
					"is_exited": false,
					"is_unjoin": false
				}
			}, {
				"user_id": "ou_919112245678741d29069abcdef02345",
				"email": "lisixxxx@a.com",
				"status": {
					"is_frozen": false,
					"is_resigned": false,
					"is_activated": true,
					"is_exited": false,
					"is_unjoin": false
				}
			},
			{
				"user_id": "ou_46a087654321a1dc920ffab8fedc3456",
				"mobile": "130xxxx1111",
				"status": {
					"is_frozen": false,
					"is_resigned": false,
					"is_activated": true,
					"is_exited": false,
					"is_unjoin": false
				}
			}, {
				"user_id": "ou_01b081675121a1dc920ffab97cdc4567",
				"mobile": "130xxxx2222",
				"status": {
					"is_frozen": false,
					"is_resigned": false,
					"is_activated": true,
					"is_exited": false,
					"is_unjoin": false
				}
			}
		]
	}
}

错误码

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