创建用户组

调用该接口创建一个用户组。用户组是飞书通讯录中基础实体之一，在用户组内可添加用户或部门资源。各类业务权限管控可以与用户组关联，从而实现高效便捷的成员权限管控。

注意事项

• 应用的通讯录权限范围必须为全部员工，否则会调用失败。了解应用通讯录权限范围，可参见权限范围资源介绍。
• 暂不支持通过该接口创建动态用户组。如需创建动态用户组参考动态用户组。

使用限制

单租户内用户组总数上限为 500（包含普通用户组和动态用户组）。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/group
HTTP Method	POST
接口频率限制	100 次/分钟
支持的应用类型	custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	contact:group 更新用户组信息
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头

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

查询参数

名称	类型	必填	描述
user_id_type	string	否	用户 ID 类型 示例值：open_id 可选值有： - open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？ 默认值：open_id 当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_type	string	否	此次调用中的部门 ID 类型。关于部门 ID 的详细介绍，可参见部门 ID 说明。 示例值：open_department_id 可选值有： - open_department_id: 由系统自动生成的部门 ID，ID 前缀固定为 od-，在租户内全局唯一。 - department_id: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。

请求体

名称	类型	必填	描述
name	string	是	用户组名字，长度不能超过 100 字符。 说明：用户组名称企业内唯一，如重复设置则会创建失败。 示例值："IT 外包组"
description	string	否	用户组描述，长度不能超过 500 字符。 默认值：空 示例值："IT服务人员的集合"
type	int	否	用户组的类型。默认取值 1，表示普通用户组。 示例值：1 可选值有： - 1: 普通用户组 - 2: 暂不支持使用该值
group_id	string	否	自定义用户组 ID。 数据校验规则： - 最大长度：64 字符 - 校验规则：数字、大小写字母的组合，不能包含空格 默认值：空，由系统生成一个默认 ID。 示例值："g122817"

请求体示例

{
    "name": "IT 外包组",
    "description": "IT服务人员的集合",
    "type": 1,
    "group_id": "g122817"
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ group_id	string	用户组 ID。后续可使用该 ID 更新、删除、查询用户组。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "group_id": "g122817"
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
500	40003	internal error	内部错误，你可以获取请求的 X-Request-Id，并联系技术支持。
400	42002	group_id invalid	用户组 ID 无效。你需要参考接口文档的用户组 ID 参数描述，修改用户组 ID 后重新尝试调用。
400	42003	group type invalid	用户组类型无效。目前创建用户组时，用户组类型仅支持传入 1，表示普通用户组类型。
400	42001	group name empty	用户组名字不得为空。请求时必须传入 name 参数值。
400	42013	group name exceed limit	用户组名字长度超过最大限制。请求时 name 参数取值的长度不能超过 100 字符。
400	42014	group description exceed limit	用户组描述长度超过最大限制。请求时 description 取值的长度不能超过 500 字符。
403	42010	not has all authority error	应用没有全部员工权限。应用的通讯录权限范围必须为全部员工，否则会调用失败。了解应用通讯录权限范围，可参见权限范围资源介绍。
400	47005	duplicate group id error	用户组 ID 重复。用户组 ID 在企业内唯一，你可以尝试更换其他 ID 后重试。
400	47009	duplicated name error	用户组名称重复。用户组名称在企业内唯一，你可以尝试更换其他名称后重试。
400	42016	user group number exceed limit	用户组数量超过最大限制。单个企业最多可创建 500 个用户组，你可以删除不再使用的用户组后，再尝试创建用户组。
400	42015	user group disable	用户组功能未开启。请联系技术支持处理。
400	40001	parameter invalid	参数错误。请检查输入参数是否设置有误，你可以参考接口文档内的参数描述，修复输入参数值。
400	42018	exist invalid dynamic group rule	存在非法的动态用户组规则，请检查请求参数后重试
400	42019	exist invalid dynamic group rule expression	动态用户组匹配规则错误
400	42020	exist unsupported dynamic group rule expression field	动态用户组的匹配规则表达式中传入了不支持的成员属性
400	42021	exist unsupported dynamic group operatrion	动态用户组的匹配规则表达式中传入了不支持的关系操作指令
400	42022	exist invalid expression value or values	动态用户组的匹配规则表达式中传入了错误、不支持的值，或者传入的单值、多值与关系操作符不匹配
400	42024	no permission to create a dynamic group	没有创建动态用户组的权限，请确认后重试
400	42025	invalid joinner rule	非法的连接规则，请修改后重试
400	42026	department scope exceed limit	部门范围超过限制，请确认后重试
400	42027	group visible scope is not valid	用户组可见范围无效

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