单次请求最多添加 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"
      }
    ]
  }
}

错误码

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

文档对您有帮助吗?