文档中心

TRAE CN

人员管理

添加成员

添加一个或多个企业成员。可仅将成员信息添加至企业并保持未激活状态，也可在添加成员的同时直接将其激活。

本接口不会发送邀请邮件。如需通过邮件邀请成员加入企业，使用 “邀请成员” 接口。

所需权限

users:write

请求说明

请求方式：POST

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

注意事项

单次请求最多添加 100 个成员。

本接口支持批量部分成功，顶层 code=0 仅表示请求处理完成，不代表每个成员均添加成功，需根据 failed_items 判断逐项结果。

邮箱在同一企业内唯一。若邮箱已属于本企业当前成员，包括 active、added、pending 等状态的成员，该项失败；若邮箱属于其他企业的活跃成员，该项同样失败。

曾被移除的成员，其状态为 removed，可通过本接口重新加入。系统会复用原 user_id，并根据 activate_member 的取值将该成员恢复为 added 或 active 状态，同时更新该成员的名称、角色和直属部门。

邮箱对应的成员账号已注销时，系统不会自动恢复该账号，该项返回 “用户不存在”。

当企业成员由外部身份源（包括火山引擎云身份中心）统一管理时，不支持通过该接口添加成员。

请求参数

请求头参数

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

请求体

参数	类型	是否必填	默认值	描述
users	array	是	-	待添加成员。范围为 1 至 100 个。
users[].email	string	是	-	成员的邮箱地址，邮箱须在同一企业内唯一。
users[].user_name	string	是	-	成员的名称。去除首尾空白后非空，最多 50 个 Unicode 字符。
users[].role	string	是	-	成员的角色： admin：管理员； member：成员。不支持创建 “超级管理员” 角色。
users[].activate_member	bool	是	-	是否立即激活成员： true：立即将成员激活为 active 状态。 false：仅将成员的信息添加至企业，成员状态为 added，不激活、不占用席位。需为每个成员单独设置该参数。因此，同一个请求中可以传入两种值。
users[].password	string	条件必填	-	成员账号的初始密码。长度至少 8 位；不能包含空白字符；大写字母、小写字母、数字、特殊字符四类中至少包含三类。提示：当 activate_member 为 true 时，该参数必填。当 activate_member 为 false 时，必须省略该参数。显式传入该参数，包括空字符串，都会导致该项失败。
users[].account_type	int	否	1	为成员分配的账号类型： 1：全端账号 2：Work 专属账号提示：旧旗舰版套餐仅支持全端账号。
users[].department_ids	string[]	否	根部门	成员的直属部门的 ID，至多传入 1 个。省略、传入 null 或 [] 时，成员会被分配到企业根部门。部门 ID 可以通过 “获取单个父部门的子部门” 接口或 ”按关键词搜索部门“ 接口获取。

响应参数

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

参数	类型	描述
success_count	int	成功添加的成员数量。
failed_items	array	添加失败的成员条目。全部添加成功时返回 []。
failed_items[].index	int	添加失败的成员在请求中传入的 users 数组中的下标，从 0 开始。
failed_items[].email	string	添加失败的成员的邮箱地址。
failed_items[].user_id	string	预留字段；当前版本的失败项通常不返回，客户端不得依赖。
failed_items[].code	int	错误码。
failed_items[].message	string	失败原因。

示例

请求示例

curl -X POST "${HOST}/openapi/v1/users/add" \​
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \​
  -H "Content-Type: application/json" \​
  -d '{​
    "users": [​
      {​
        "email": "alice@example.com",​
        "user_name": "Added Member",​
        "role": "member",​
        "activate_member": false​
      },​
      {​
        "email": "john@example.com",​
        "user_name": "Active Member",​
        "role": "member",​
        "activate_member": true,​
        "password": "Aa123456!",​
        "department_ids": ["20001"]​
      }​
    ]​
  }'​

响应示例

{​
  "code": 0,​
  "message": "success",​
  "request_id": "req_xxx",​
  "data": {​
    "success_count": 1,​
    "failed_items": [​
      {​
        "index": 1,​
        "email": "john@example.com",​
        "code": 30001,​
        "message": "user already exists in this tenant"​
      }​
    ]​
  }​
}​

错误码

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

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

这个页面对您有帮助吗？

有用

无用