创建单位

调用该接口创建一个单位。

前提条件

单位属于付费功能，企业需要开通对应的飞书版本才可以使用。了解更多，可参见单位管理。

使用限制

单租户内单位总数上限为 1,000。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/unit
HTTP Method	POST
接口频率限制	20 次/秒
支持的应用类型	custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	contact:unit 更新单位信息

请求头

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

请求体

名称	类型	必填	描述
unit_id	string	否	自定义单位 ID，租户内唯一，创建后不可修改。 数据校验规则： 1 ~ 64 个字符，仅支持字母、数字。 默认值：空，若不传值则由系统自动生成一个默认 ID。 示例值："BU121"
name	string	是	单位名字。 数据校验规则： 1 ~ 100 个字符。 注意：在租户内，传入的 name 和 unit_type 不允许同时重复。例如，已存在一个名字 A、类型 A的单位，此时再创建一个名字 A、类型 A 的单位将会创建失败。 示例值："消费者事业部"
unit_type	string	是	自定义单位类型，创建后不可修改。 数据校验规则： 1 ~ 100 个字符。 注意：在租户内，传入的 name 和 unit_type 不允许同时重复。例如，已存在一个名字 A、类型 A的单位，此时再创建一个名字 A、类型 A 的单位将会创建失败。 示例值："子公司"

请求体示例

{
    "unit_id": "BU121",
    "name": "消费者事业部",
    "unit_type": "子公司"
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ unit_id	string	单位 ID。后续可使用该 ID 对单位进行修改、删除、查询以及绑定部门等操作。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "unit_id": "BU121"
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
500	40003	internal error	内部错误，请获取请求的 X-Request-Id，并向技术支持进行反馈。
400	43050	unit feature is prohibited	单位是旗舰版功能，需企业开通相应版本。了解更多，可参见单位管理。
400	43051	unit_id invalid	单位 ID 无效。你需要参考接口文档内的参数描述，设置正确的单位 ID 后重试。
400	43052	unit name invalid	非法的单位名字，长度需为 1 ~ 100 个字符。
400	43053	unit type invalid	非法的单位类型，长度需为 1 ~ 100 个字符。
400	43056	duplicate unit id error	自定义的单位 ID 已存在，请更换后重试。
400	43055	unit name and type repeat	单位名字和类型同时重复。同一企业内，不允许单位名字和类型同时重复。
400	43059	unit number exceed limit	单位数量超过上限。单租户内单位数量不得超过 1,000 个。

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