文档中心

TRAE CN

人员管理

批量获取成员信息

批量获取企业成员的信息。可通过成员 ID、邮箱，或两者组合精确查询成员。

所需权限

users:read

请求说明

请求方式：POST

请求地址：{域名}/openapi/v1/users/batch-get

注意事项

user_ids 与 emails 至少传入一个。系统会分别去除重复的成员 ID 和邮箱；去重后，两个数组的元素总数不得超过 100。同一成员同时通过 ID 和邮箱传入时，仍按两个元素计数，但响应中该成员只返回一次。

items 中的成员按固定顺序返回：先按 user_ids 首次出现顺序返回命中成员，再按 emails 首次出现顺序返回命中成员。

不属于当前企业的成员 ID 或邮箱按未找到处理，不会返回其所属的其他企业中的信息。

已注销的成员按未找到处理；曾被移除的成员会正常返回，状态为 removed。

请求参数

请求头参数

Header 参数	是否必填	描述
Authorization	是	固定取值为 Bearer {access_token}。关于如何获取访问令牌，参考鉴权。
Content-Type	是	固定取值为 application/json。

请求体参数

参数	类型	是否必填	默认值	描述
user_ids	string[] 或 int[]	条件必填	-	目标成员的 ID 列表。与 emails 至少传入一个。每项可为十进制字符串或无小数整数。建议使用字符串，避免大整数精度损失。对于字符串类型 ID，查询前会先去除首尾空白。成员 ID 可以通过 “获取成员列表” 接口获取。
emails	string[]	条件必填	-	目标成员的邮箱列表。与 user_ids 至少传入一个。系统会在查询前去除首尾空白，然后按不区分大小写的方式查询。成员邮箱可以通过 “获取成员列表” 接口获取。

响应参数

该接口独有的响应参数如下，参数位于 data 中。通用响应参数参考此文档。

参数	类型	描述
items	array	成功查询到的成员列表。
items[].user_id	int64	成员的 ID。
items[].user_id_str	string	成员 ID 的字符串形式。
items[].user_name	string	成员的名称。
items[].email	string	成员的邮箱。返回系统内保存的规范邮箱。
items[].role	string	成员的角色： super_admin：超级管理员 admin：管理员 member：成员
items[].status	string	成员的状态： active：账号/席位使用中 added：已加入但未激活 pending：邀请中 removed：已移除
items[].join_time	int64	成员加入企业的时间（毫秒时间戳）。
items[].account_type	int	成员的账号类型： 1：全端账号 2：Work 专属账号提示：旧旗舰版套餐仅支持全端账号。
items[].departments	array	成员直属部门信息列表。
items[].departments[].department_id	string	直属部门的 ID。
items[].departments[].name	string	直属部门的名称。
items[].departments[].full_path	string	直属部门的完整路径。各级部门名称以 / 分隔。
items[].not_found_user_ids	string[]	未找到、已注销或不属于当前企业的成员 ID。
items[].not_found_emails	string[]	未找到、已注销或不属于当前企业的邮箱。

示例

请求示例

curl -X POST "${HOST}/openapi/v1/users/batch-get" \​
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \​
  -H "Content-Type: application/json" \​
  -d '{​
    "user_ids": ["123456"],​
    "emails": ["alice@example.com", "john@example.com"]​
  }'​

响应示例

{​
  "code": 0,​
  "message": "success",​
  "request_id": "req_xxx",​
  "data": {​
    "items": [​
      {​
        "user_id": 123456,​
        "user_id_str": "123456",​
        "user_name": "Alice",​
        "email": "alice@example.com",​
        "role": "member",​
        "status": "active",​
        "join_time": 1780000000000,​
        "account_type": 1,​
        "departments": [​
          {​
            "department_id": "20001",​
            "name": "研发一部",​
            "full_path": "示例企业/研发中心/研发一部"​
          }​
        ]​
      }​
    ],​
    "not_found_user_ids": [],​
    "not_found_emails": ["john@example.com"]​
  }​
}​

错误码

若该接口的请求返回错误码，参考错误码文档进行排查。

最近更新时间：2026.10.10 17:34:32

这个页面对您有帮助吗？

有用

无用