文档中心

TRAE CN

人员管理

获取成员列表

分页获取企业成员列表，可按部门与账号类型过滤。

所需权限

users:read

请求说明

请求方式：GET

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

请求参数

请求头参数

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

查询参数

参数	类型	是否必填	默认值	描述
page	int	否	1	需返回的页数。
page_size	int	否	100	每页返回的成员数量，最多 500 个。
account_type	int	否	-	账号类型，用于按账号类型筛选成员： 1：全端账号 2：Work 专属账号若省略该参数，则返回全部账号类型的成员。
department_id	string	否	-	目标部门的 ID，用于按部门筛选成员。
include_subtree	bool	否	true	是否包含目标部门的子部门的成员。 true：包含 false：不包含该参数仅在传入 department_id 参数时生效。若省略，则返回全部子部门的成员。
include_removed	bool	否	false	是否包含已移除的成员： true：同时返回当前仍在企业中的成员和已被移除的成员。 false：仅返回当前仍在企业中的成员

响应参数

该接口独有的响应参数如下，参数位于 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：已移除（仅可能在 include_removed=true 时返回）
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	直属部门的完整路径。各级部门名称以 / 分隔。

示例

请求示例

curl -X GET "${HOST}/openapi/v1/users?page=1&page_size=100&department_id=20001&include_subtree=false" \​
  -H "Authorization: Bearer ${ACCESS_TOKEN}"​

响应示例

{​
  "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": "added",​
        "join_time": 1700000000000,​
        "account_type": 1,​
        "departments": [​
          {​
            "department_id": "10001",​
            "name": "研发部",​
            "full_path": "公司/研发部"​
          }​
        ]​
      }​
    ],​
    "pagination": {​
      "page": 1,​
      "page_size": 100,​
      "total": 1,​
      "total_pages": 1​
    }​
  }​
}​

错误码

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

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

这个页面对您有帮助吗？

有用

无用