服务端 API/通讯录/用户/批量获取用户信息 # 批量获取用户信息 该接口用于批量获取通讯录用户的信息。 **注意事项**：- 批量查询接口目前不返回用户的席位（assign_info）和部门路径信息（department_path）。 ## 请求 基本 |   ---|--- HTTP URL | https://open.larksuite.com/open-apis/contact/v3/users/batch HTTP Method | GET 接口频率限制 | [1000 次/分钟、50 次/秒](https://open.larksuite.com/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 获取通讯录基本信息(contact:contact.base:readonly) 字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
以应用身份读取通讯录(contact:contact:readonly_as_app)
查询用户席位信息(contact:user.assign_info:read)
获取用户基本信息(contact:user.base:readonly)
获取用户组织架构信息(contact:user.department:readonly)
获取成员所在部门路径(contact:user.department_path:readonly)
查看成员的虚线上级 ID(contact:user.dotted_line_leader_info.read)
获取用户受雇信息(contact:user.employee:readonly)
查看成员工号(contact:user.employee_number:read)
获取用户性别(contact:user.gender:readonly)
分配用户席位(contact:user.subscription_ids:write)
获取用户 user ID(contact:user.employee_id:readonly)
查看成员数据驻留地(contact:user.user_geo)
获取用户邮箱信息(contact:user.email:readonly)
查询用户所属的工作序列(contact:user.job_family:readonly)
查询用户职级(contact:user.job_level:readonly)
获取用户手机号(contact:user.phone:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) ### 查询参数 名称 | 类型 | 必填 | 描述 ---|---|---|--- user_ids | string\[\] | 是 | 用户ID，类型需要与查询参数中的user_id_type保持一致。单次最大请求数量50。
例如user_id_type=open_id，user_id的类型需为open_id
不同ID的说明参见 [用户相关的 ID 概念](https://open.larksuite.com/document/home/user-identity-introduction/introduction)
如需一次查询多个用户ID，可通过将同一参数名多次传递，并且每次传递不同的参数值。例如：
`https://{url}?user_ids={user_id1}&user_ids={user_id2}`
其中：
* `user_ids`是参数名，可以多次传递
* `user_id1`和`user_id2`是参数值
**示例值**：7be5fg user_id_type | string | 否 | 用户 ID 类型
**示例值**：open_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) department_id_type | string | 否 | 指定查询结果中用户关联的部门ID类型
**示例值**：open_department_id
**可选值有**：
- open_department_id：以open_department_id来标识部门
- department_id：以自定义department_id来标识部门
**默认值**：`open_department_id` ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- items | user\[\] | 查询到的用户信息，其中异常的用户ID不返回结果。 union_id | string | 用户的union_id，应用开发商发布的不同应用中同一用户的标识，不同ID的说明参见 [用户相关的 ID 概念](https://open.larksuite.com/document/home/user-identity-introduction/introduction) user_id | string | 用户的user_id，租户内用户的唯一标识，不同ID的说明参见 [用户相关的 ID 概念](https://open.larksuite.com/document/home/user-identity-introduction/introduction)
**字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly) open_id | string | 用户的open_id，应用内用户的唯一标识，不同ID的说明参见 [用户相关的 ID 概念](https://open.larksuite.com/document/home/user-identity-introduction/introduction) name | string | 用户名
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户基本信息(contact:user.base:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) en_name | string | 英文名
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户基本信息(contact:user.base:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) nickname | string | 别名
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户基本信息(contact:user.base:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) email | string | 邮箱
注意：
1. 非中国大陆手机号成员必须同时添加邮箱
2. 邮箱不可重复
**字段权限要求**：
获取用户邮箱信息(contact:user.email:readonly) mobile | string | 手机号
注意：
1. 在本企业内不可重复
2. 未认证企业仅支持添加中国大陆手机号，通过Lark认证的企业允许添加海外手机号
3. 国际电话区号前缀中必须包含加号 +
4. 该 mobile 字段在海外版Lark非必填
**字段权限要求**：
获取用户手机号(contact:user.phone:readonly) mobile_visible | boolean | 手机号码可见性，true 为可见，false 为不可见，目前默认为 true。不可见时，组织员工将无法查看该员工的手机号码 gender | int | 性别
**可选值有**：
- 0：保密
- 1：男
- 2：女
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户性别(contact:user.gender:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) avatar_key | string | 头像的文件Key avatar | avatar_info | 用户头像信息
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户基本信息(contact:user.base:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) avatar_72 | string | 72*72像素头像链接 avatar_240 | string | 240*240像素头像链接 avatar_640 | string | 640*640像素头像链接 avatar_origin | string | 原始头像链接 status | user_status | 用户状态
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) is_frozen | boolean | 是否冻结 is_resigned | boolean | 是否离职 is_activated | boolean | 是否激活 is_exited | boolean | 是否主动退出，主动退出一段时间后用户会自动转为已离职 is_unjoin | boolean | 是否未加入，需要用户自主确认才能加入团队 department_ids | string\[\] | 用户所属部门的ID列表，一个用户可属于多个部门。
ID值的类型与查询参数中的department_id_type 对应。
不同 ID 的说明与department_id的获取方式参见 [部门ID说明](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview#23857fe0)
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户组织架构信息(contact:user.department:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) leader_user_id | string | 用户的直接主管的用户ID，ID值与查询参数中的user_id_type 对应。
不同 ID 的说明参见 [用户相关的 ID 概念](https://open.larksuite.com/document/home/user-identity-introduction/introduction)
获取方式参见[如何获取user_id](https://open.larksuite.com/document/home/user-identity-introduction/how-to-get)
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户组织架构信息(contact:user.department:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) city | string | 城市
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) country | string | 国家或地区Code缩写，具体写入格式请参考 [国家/地区码表](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/country-code-description)
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) work_station | string | 工位
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) join_time | int | 入职时间，时间戳格式，表示从1970年1月1日开始所经过的秒数
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) is_tenant_manager | boolean | 是否是租户超级管理员
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) employee_no | string | 工号
**字段权限要求（满足任一）**：
获取用户受雇信息(contact:user.employee:readonly)
查看成员工号(contact:user.employee_number:read)
以应用身份读取通讯录(contact:contact:readonly_as_app)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) employee_type | int | 员工类型，可选值有：
- `1`：正式员工
- `2`：实习生
- `3`：外包
- `4`：劳务
- `5`：顾问
同时可读取到自定义员工类型的 int 值，可通过下方接口获取到该租户的自定义员工类型的名称，参见[获取人员类型](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/list)
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) orders | user_order\[\] | 用户排序信息。
用于标记通讯录下组织架构的人员顺序，人员可能存在多个部门中，且有不同的排序。
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户组织架构信息(contact:user.department:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) department_id | string | 排序信息对应的部门ID， ID值与查询参数中的department_id_type 对应。
表示用户所在的、且需要排序的部门。
不同 ID 的说明参见及获取方式参见 [部门ID说明](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) user_order | int | 用户在其直属部门内的排序，数值越大，排序越靠前 department_order | int | 用户所属的多个部门间的排序，数值越大，排序越靠前 is_primary_dept | boolean | 标识用户的唯一主部门，主部门为用户所属部门中排序第一的部门(department_order最大) custom_attrs | user_custom_attr\[\] | 自定义属性
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) type | string | 自定义字段类型
- `TEXT`：文本
- `HREF`：网页
- `ENUMERATION`：枚举
- `PICTURE_ENUM`：图片
- `GENERIC_USER`：用户
具体说明参见常见问题的[用户接口相关问题](https://open.larksuite.com/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN#77061525) id | string | 自定义字段ID value | user_custom_attr_value | 自定义属性取值 text | string | 字段类型为`TEXT`时该参数定义字段值，必填；字段类型为`HREF`时该参数定义网页标题，必填 url | string | 字段类型为 HREF 时，该参数定义默认 URL，例如手机端跳转小程序，PC端跳转网页 pc_url | string | 字段类型为 HREF 时，该参数定义PC端 URL option_id | string | 选项类型的ID。
表示 成员详情/自定义字段 中选项选中的ID option_value | string | 选项类型的值。
表示 成员详情/自定义字段 中选项选中的值 name | string | 选项类型为图片时，表示图片的名称 picture_url | string | 图片链接 generic_user | custom_attr_generic_user | 字段类型为 GENERIC_USER 时，该参数定义引用人员 id | string | 用户的user_id ，具体参见[用户相关的 ID 概念](https://open.larksuite.com/document/home/user-identity-introduction/introduction) type | int | 用户类型:
1：用户
目前固定为1，表示用户类型 enterprise_email | string | 企业邮箱，请先确保已在管理后台启用Lark邮箱服务
创建用户时，企业邮箱的使用方式参见[用户接口相关问题](https://open.larksuite.com/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN#77061525)
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) job_title | string | 职务
**字段权限要求（满足任一）**：
以应用身份读取通讯录(contact:contact:readonly_as_app)
获取用户受雇信息(contact:user.employee:readonly)
以应用身份访问通讯录(contact:contact:access_as_app)
读取通讯录(contact:contact:readonly) is_frozen | boolean | 是否冻结用户 geo | string | 数据驻留地
**字段权限要求**：
查看成员数据驻留地(contact:user.user_geo) job_level_id | string | 职级ID
**字段权限要求**：
查询用户职级(contact:user.job_level:readonly) job_family_id | string | 序列ID
**字段权限要求**：
查询用户所属的工作序列(contact:user.job_family:readonly) subscription_ids | string\[\] | 分配给用户的席位ID列表
**字段权限要求**：
分配用户席位(contact:user.subscription_ids:write) assign_info | user_assign_info\[\] | 用户席位列表
**字段权限要求**：
查询用户席位信息(contact:user.assign_info:read) subscription_id | string | 席位id license_plan_key | string | license_plan_key product_name | string | 席位名称 i18n_name | product_i18n_name | 国际化名称 zh_cn | string | 席位中文名 ja_jp | string | 席位日文名 en_us | string | 席位英文名 start_time | string | 席位起始时间 end_time | string | 席位结束时间 department_path | department_detail\[\] | 部门路径
**字段权限要求**：
获取成员所在部门路径(contact:user.department_path:readonly) department_id | string | 部门ID department_name | department_path_name | 部门名 name | string | 部门名 i18n_name | department_i18n_name | 部门国际化名 zh_cn | string | 部门的中文名 ja_jp | string | 部门的日文名 en_us | string | 部门的英文名 department_path | department_path | 部门路径 department_ids | string\[\] | 部门路径IDs department_path_name | department_path_name | 部门路径名字 name | string | 部门名 i18n_name | department_i18n_name | 部门国际化名 zh_cn | string | 部门的中文名 ja_jp | string | 部门的日文名 en_us | string | 部门的英文名 dotted_line_leader_user_ids | string\[\] | 虚线上级ID
**字段权限要求**：
查看成员的虚线上级 ID(contact:user.dotted_line_leader_info.read) ### 响应体示例 ```json { "code": 0, "msg": "success", "data": { "items": [ { "union_id": "on_94a1ee5551019f18cd73d9f111898cf2", "user_id": "3e3cf96b", "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62", "name": "张三", "en_name": "San Zhang", "nickname": "Alex Zhang", "email": "zhangsan@gmail.com", "mobile": "13011111111 (其他例子，中国大陆手机号: 13011111111 或 +8613011111111, 非中国大陆手机号: +41446681800)", "mobile_visible": false, "gender": 1, "avatar_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g", "avatar": { "avatar_72": "https://foo.icon.com/xxxx", "avatar_240": "https://foo.icon.com/xxxx", "avatar_640": "https://foo.icon.com/xxxx", "avatar_origin": "https://foo.icon.com/xxxx" }, "status": { "is_frozen": false, "is_resigned": false, "is_activated": true, "is_exited": false, "is_unjoin": false }, "department_ids": [ "od-4e6ac4d14bcd5071a37a39de902c7141" ], "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62", "city": "杭州", "country": "CN", "work_station": "北楼-H34", "join_time": 2147483647, "is_tenant_manager": false, "employee_no": "1", "employee_type": 1, "orders": [ { "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141", "user_order": 100, "department_order": 100, "is_primary_dept": true } ], "custom_attrs": [ { "type": "TEXT", "id": "DemoId", "value": { "text": "DemoText", "url": "http://www.fs.cn", "pc_url": "http://www.fs.cn", "option_id": "option", "option_value": "option", "name": "name", "picture_url": "https://xxxxxxxxxxxxxxxxxx", "generic_user": { "id": "9b2fabg5", "type": 1 } } } ], "enterprise_email": "demo@mail.com", "job_title": "xxxxx", "is_frozen": false, "geo": "cn", "job_level_id": "mga5oa8ayjlp9rb", "job_family_id": "mga5oa8ayjlp9rb", "subscription_ids": [ "23213213213123123" ], "assign_info": [ { "subscription_id": "7079609167680782300", "license_plan_key": "suite_enterprise_e5", "product_name": "旗舰版 E5", "i18n_name": { "zh_cn": "zh_cn_name", "ja_jp": "ja_jp_name", "en_us": "en_name" }, "start_time": "1674981000", "end_time": "1674991000" } ], "department_path": [ { "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141", "department_name": { "name": "测试部门名1", "i18n_name": { "zh_cn": "测试部门名1", "ja_jp": "試験部署名 1", "en_us": "Testing department name 1" } }, "department_path": { "department_ids": [ "od-4e6ac4d14bcd5071a37a39de902c7141" ], "department_path_name": { "name": "测试部门名1", "i18n_name": { "zh_cn": "测试部门名1", "ja_jp": "試験部署名 1", "en_us": "Testing department name 1" } } } } ], "dotted_line_leader_user_ids": [ "ou_7dab8a3d3cdcc9da365777c7ad535d62" ] } ] } } ``` ### 错误码 HTTP状态码 | 错误码 | 描述 | 排查建议 ---|---|---|--- 400 | 40001 | invalid parameter | 参数错误。 400 | 41050 | no user authority | 操作的用户需在通讯录权限范围中，[了解更多](https://open.larksuite.com/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) 403 | 40004 | no dept. authority | 操作的部门需在通讯录权限范围中，[了解更多](https://open.larksuite.com/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)