文档反馈
向一个或多个邮箱发送邀请邮件，受邀成员可以通过邮件加入企业并激活账号或席位。若不希望发送邀请邮件，使用 “添加成员” 接口。
所需权限
users:write
请求说明
- 请求方式：
POST - 请求地址：
{域名}/openapi/v1/users/invite
注意事项
- 单次请求最多邀请 20 个成员。
- 本接口支持批量部分成功，顶层
code=0仅表示请求处理完成，不代表每个成员均邀请成功，需根据failed_items判断逐项结果。 - 若邮箱已属于本企业当前成员，或属于其他企业的活跃成员，该项失败。
- 若成员当前状态不允许再次发送邀请，例如状态为 “邀请发送中” 时，该项失败。
- 当企业成员由外部身份源（包括火山引擎云身份中心）统一管理时，不支持通过该接口邀请成员。
请求参数
请求头参数
| Header 参数 | 是否必填 | 描述 |
|---|---|---|
Authorization |
是 | 固定取值为 Bearer {access_token}。关于如何获取访问令牌，参考鉴权。 |
Content-Type |
是 | 固定取值为 application/json。 |
请求体参数
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
users |
array | 是 | - | 待邀请成员列表。范围为 1 至 20 个。 |
users[].email |
string | 是 | - | 待邀请成员的邮箱地址，须在同一企业内唯一。 |
|
|
string |
是 |
- |
待邀请成员的角色：
|
|
|
string |
否 |
- |
成员的名称。 系统不会自动生成成员名称。省略该参数不会导致该成员邀请失败。传入时去除首尾空白后不能为空，最多 50 个 Unicode 字符。 |
|
|
int |
否 |
|
为成员分配的账号类型：
提示：旧旗舰版套餐仅支持全端账号。 |
|
|
string[] |
否 |
- |
成员的直属部门的 ID，至多传入 1 个。 省略、传入 部门 ID 可以通过 “获取单个父部门的子部门” 接口或 ”按关键词搜索部门“ 接口获取。 |
响应参数
该接口独有的响应参数如下，参数位于 data 中。通用响应参数参考此文档。
| 参数 | 类型 | 描述 |
|---|---|---|
success_count |
int | 成功邀请的成员数量。 |
failed_items |
array | 邀请失败的成员列表。全部成功时返回 []。 |
failed_items[].index |
int | 邀请失败的成员在请求中传入的 users 数组中的下标，从 0 开始。 |
failed_items[].email |
string | 邀请失败的成员邮箱（即请求中传入的原始值）。 |
failed_items[].code |
int | 错误码。 |
failed_items[].message |
string | 失败原因。 |
warnings |
string[] | 非致命问题的提示信息，例如成功邀请但缺少成员名称时，可能返回 user_name_missing。无提示时省略。 |
示例
请求示例
curl -X POST "${HOST}/openapi/v1/users/invite" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"users": [
{"email": "invitee@example.com", "role": "member"}
]
}'
响应示例
{
"code": 0,
"message": "success",
"request_id": "req_xxx",
"data": {
"success_count": 1,
"failed_items": [],
"warnings": ["user_name_missing"]
}
}
错误码
若该接口的请求返回错误码，参考错误码文档进行排查。