批量添加用户组成员

调用该接口向指定的普通用户组内添加一个或多个成员。

注意事项

• 目前仅支持添加用户类型的成员，暂不支持添加部门类型的成员。

• 如果应用的通讯录权限范围是 全部员工，则可以将当前租户内的任何用户添加到任何用户组当中。如果应用的通讯录权限范围不是 全部员工，则所要添加的用户以及对应的用户组，均需要在应用的通讯录权限范围内。了解通讯录权限范围，可参见权限范围资源介绍。

使用限制

单租户内单个普通用户组的成员数量上限为 100,000。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/group/:group_id/member/batch_add
HTTP Method	POST
接口频率限制	100 次/分钟
支持的应用类型	custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	contact:group 更新用户组信息

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

路径参数

名称	类型	描述
group_id	string	用户组 ID。 用户组 ID 可在创建用户组时从返回值中获取，你也可以调用查询用户组列表接口，获取用户组的 ID。 示例值："test_group"

请求体

名称	类型	必填	描述
members	memberlist\[\]	否	待添加成员信息。 数据校验规则： - 长度范围：1 ～ 100
└ member_id	string	是	添加的用户 ID，ID 类型与 member_id_type 的取值保持一致。不同类型的 ID 获取方式可参见： - 如何获取用户 open_id - 如何获取用户 union_id - 如何获取用户 user_id 示例值："u287xj12"
└ member_type	string	是	用户组成员的类型，目前仅支持选择 user，表示用户类型。 示例值："user"
└ member_id_type	string	否	当 member_type 取值为 user时，该参数必填，需通过该参数设置用户 ID 类型。包括： - open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。 - union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。 - user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用中都保持一致。User ID 主要用于在不同的应用间打通用户数据。 示例值："user_id"

请求体示例

{
    "members": [
        {
            "member_id": "u287xj12",
            "member_type": "user",
            "member_id_type": "user_id"
        }
    ]
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ results	member_result\[\]	添加成员的操作结果。
└ member_id	string	成员 ID。ID 类型与请求参数中，每一个成员对应的 member_id_type 取值保持一致。
└ code	int	结果响应码，取值为 0 表示成功。取值非 0 表示当前的 member_id 存在问题，具体的错误码排查方案可参考本文的错误码列表或者通用错误码。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "results": [
            {
                "member_id": "u287xj12",
                "code": 0
            }
        ]
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
403	41050	no user authority error	无用户权限。需将当前操作的用户添加到应用或用户的权限范围内。根据调用 API 的身份不同，解决方案也不同，具体说明如下： - 使用 tenant_access_token 调用 API 当前操作的用户需要添加在应用的通讯录权限范围内。通讯录权限范围定义了应用在调用通讯录 API 时可获取的部门、用户的数据范围。应用无法访问不在通讯录权限范围内的数据。 由开发者登录开发者后台，在应用详情页的 开发配置 > 权限管理 > 数据权限 页面内，配置 通讯录权限范围，添加指定用户。 已发布的应用企业管理员可在管理后台 > 工作台 > 应用管理 页面，修改应用的通讯录权限范围。 - 使用 user_access_token 调用 API 当你使用用户身份调用通讯录 API 时，可操作的权限范围不受应用的通讯录权限范围影响，而是受当前用户的组织架构可见范围影响，该范围限制了用户在企业内可见的组织架构数据范围。 由企业管理员在管理后台 > 安全 > 成员权限 页面中，点击 组织架构可见范围 进行管理。 完整介绍参见权限范围资源介绍。
500	40003	internal error	内部错误，请获取请求的 X-Request-Id，并向技术支持进行反馈。
400	40001	param error	参数错误。请检查请求时传入的参数是否有误。
400	42012	group member user reached the upper limit	用户组的用户数量达到上限。单租户单个普通用户组成员数量上限为 100,000，但同时单租户内所有普通用户组的成员总数上限为租户用户数量的 10 倍。
200	42005	member is already in group	当前添加的成员已经存在用户组中，无需重复添加。
400	42006	user has resigned error	用户已离职，无法添加。
400	41073	invalid member_id	成员 ID 无效。你需要参考接口文档的 member_id 参数描述，传入正确的成员 ID。
400	41074	invalid member_type	无效的成员类型。你需要按照接口文档内 member_type 的参数描述设置正确的值。
400	41071	invalid member_id_type	无效的成员 ID 类型。你需要按照接口文档内 member_id_type 的参数描述设置正确的值。
400	42002	invalid group_id	用户组 ID 无效。你可以调用查询用户组列表接口，获取准确的用户组 ID。
403	42009	no user group authority	缺少用户组权限。应用的通讯录权限范围需包含当前操作的用户组。了解应用的通讯录权限范围，可参见权限范围资源介绍。

更多错误码信息，参见通用错误码。