# 创建部门 本接口用于用于在企业通讯录中创建新部门，支持设置部门名称、父部门、负责人等信息。 **注意事项**：注意： - 只能在当前应用的通讯录授权范围内的部门下创建部门，如果要在根部门下创建子部门，必须拥有全员权限。可以在 开发者后台-应用详情-权限管理中 查看通讯录授权范围。 - 本接口中支持的user_access_token 默认为管理员用户，将校验管理员管理范围。当用户有多个管理员身份均可创建部门时，管理员管理范围取最大集。管理员权限可查看帮助中心文档：[管理员创建管理员角色及分配权限](https://www.feishu.cn/hc/zh-CN/articles/360043495213-%E7%AE%A1%E7%90%86%E5%91%98%E5%88%9B%E5%BB%BA%E7%AE%A1%E7%90%86%E5%91%98%E8%A7%92%E8%89%B2%E5%8F%8A%E5%88%86%E9%85%8D%E6%9D%83%E9%99%90#tabs0|lineguid-dU31C) - 拥有本接口权限后，即可写入部门信息。但创建部门后仅返回应用有权限的字段数据，如果需要指定字段请按照文档中的描述申请对应权限。 - 本接口仅对自建应用开放。 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/directory/v1/departments HTTP Method | POST 接口频率限制 | [5 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 创建部门(directory:department.create:write)
创建、更新、删除部门(directory:department:write) 字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
查看员工自定义 ID(directory:employee.base.external_id:read) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) Content-Type | string | 是 | **固定值**："application/json; charset=utf-8" ### 查询参数 名称 | 类型 | 必填 | 描述 ---|---|---|--- employee_id_type | string | 否 | 用户 ID 类型
**示例值**：open_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- employee_id：企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。
获取employee_id的方式：
- 企业管理员在 管理后台 > 组织架构 > 成员与部门 页面，点击 成员详情，查询员工ID
- 通过 [批量获取员工列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/directory-v1/employee/filter) 的接口，通过手机号或邮箱查询员工ID。
**默认值**：`open_id`
**当值为 `employee_id`，字段权限要求**：
查看员工自定义 ID(directory:employee.base.external_id:read) department_id_type | string | 否 | 此次调用中使用的部门ID的类型
**示例值**：open_department_id
**可选值有**：
- department_id：用来标识租户内一个唯一的部门
- open_department_id：用来在具体某个应用中标识一个部门，同一个部门 在不同应用中的 open_department_id 不相同。
**默认值**：`open_department_id` ### 请求体 名称 | 类型 | 必填 | 描述 ---|---|---|--- department | create_department | 是 | 创建部门 custom_department_id | string | 否 | 标识租户内一个唯一的部门，支持自定义，未自定义时系统自动生成。ID支持修改。注意：
1. 除需要满足正则规则外，同时不能以od-开头
2. 正则校验：^[a-zA-Z0-9][a-zA-Z0-9_\-@.]{0,63}$
**示例值**："eersdf" name | i18n_text | 否 | 部门名称，最多可输入 100 字 default_value | string | 是 | 默认值
**示例值**："张三
**数据校验规则**：
长度范围：1-64 字符" i18n_value | map<string, string> | 否 | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
**示例值**：{
"zh_cn": "中文",
"ja_jp": "ja_jp_name",
"en_us": "en_us_name"
} parent_department_id | string | 否 | 父部门ID，与department_id_type类型保持一致
。如果父部门为根部门，该参数值为 “0”
**示例值**："h121900" leaders | department_leader\[\] | 否 | 部门负责人
**数据校验规则**：
- 长度范围：`0` ～ `20` leader_type | int | 是 | 部门负责人类型
**示例值**：1
**可选值有**：
- 1：主
- 2：副 leader_id | string | 是 | 部门负责人ID，与employee_id_type类型保持一致
**示例值**："u273y71" order_weight | string | 否 | 在上级部门下的排序权重，返回结果按order_weight降序排列
**示例值**："100" enabled_status | boolean | 否 | 是否启用
**示例值**：true custom_field_values | custom_field_value\[\] | 否 | 部门自定义字段值
**数据校验规则**：
- 长度范围：`0` ～ `100` field_type | string | 否 | 自定义字段类型
**示例值**："1"
**可选值有**：
- 1：多行文本
- 2：网页链接
- 3：枚举选项
- 4：人员
- 9：电话
- 10：多选枚举类型(目前仅支持文本类型)
- 11：人员列表 text_value | i18n_text | 否 | 文本字段值 default_value | string | 是 | 默认值
**示例值**："张三" i18n_value | map<string, string> | 否 | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
**示例值**：{
"zh_cn": "中文",
"ja_jp": "ja_jp_name",
"en_us": "en_us_name"
} url_value | url_value | 否 | 网页链接字段值 link_text | i18n_text | 是 | 网页标题 default_value | string | 是 | 默认值
**示例值**："张三" i18n_value | map<string, string> | 否 | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
**示例值**：{"zh_cn":"张三"} url | string | 是 | 移动端网页链接
**示例值**："https://m.bytedance.com/afnasjfna" pcurl | string | 是 | 桌面端网页链接
**示例值**："http://www.fs.cn" enum_value | enum_value | 否 | 枚举字段值 enum_ids | string\[\] | 是 | 选项结果ID
**示例值**：["dsa213sa"]
**数据校验规则**：
- 长度范围：`0` ～ `100` enum_type | string | 是 | 选项类型
**示例值**："1"
**可选值有**：
- 1：文本
- 2：图片 user_values | user_value\[\] | 否 | 人员字段值
**数据校验规则**：
- 长度范围：`0` ～ `100` ids | string\[\] | 是 | 人员ID，与employee_id_type类型保持一致
**示例值**：["asdbjw1s"]
**数据校验规则**：
- 长度范围：`0` ～ `100` phone_value | phone_value | 否 | 电话字段值 phone_number | string | 是 | 电话号
**示例值**："18812345678" extension_number | string | 否 | 分机号
**示例值**："234234234
长度范围：0-99字符" field_key | string | 否 | 自定义字段key
**示例值**："C-1000001" ### 请求体示例 ```json {"department":{"custom_department_id":"eersdf", "name":{"default_value":"张三 **数据校验规则**： 长度范围：1-64 字符", "i18n_value":{ "zh_cn": "中文", "ja_jp": "ja_jp_name", "en_us": "en_us_name" }}, "parent_department_id":"h121900", "leaders":[{ "leader_type": 1, "leader_id": "u273y71" }], "order_weight":"100", "enabled_status":true, "custom_field_values":[{"field_type":"1", "text_value":{"default_value":"张三", "i18n_value":{ "zh_cn": "中文", "ja_jp": "ja_jp_name", "en_us": "en_us_name" }}, "url_value":{"link_text":{"default_value":"张三", "i18n_value":{"zh_cn":"张三"}}, "url":"https://m.bytedance.com/afnasjfna", "pcurl":"http://www.fs.cn"}, "enum_value":{"enum_ids":["dsa213sa"], "enum_type":"1"}, "user_values":[{ "ids": [ "asdbjw1s" ] }], "phone_value":{"phone_number":"18812345678", "extension_number":"234234234 长度范围：0-99字符"}, "field_key":"C-1000001"}]}} ``` ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- department_id | string | 部门ID ### 响应体示例 ```json { "code": 0, "msg": "success", "data": { "department_id": "eesdasd" } } ``` ### 错误码 HTTP状态码 | 错误码 | 描述 | 排查建议 ---|---|---|--- 400 | 2221305 | Request parameter error | 请求参数错误，具体参照错误信息。 400 | 2221306 | ExternalID repeat | 租户内自定义ID重复，请更换自定义ID后重试。 400 | 2221307 | Exceed department limit | 部门数量超限，请减少部门数量至限制内。 400 | 2221309 | Department does not exist | 父部门不存在，请确认父部门ID是否正确。 400 | 2221311 | Internationalized name duplication | 部门的英文名称已存在，请使用其他名称 或 部门的日文名称已存在，请使用其他名称 400 | 2221312 | Exceed department level depth | 部门层级过深，部门层级上限为25 400 | 2221313 | ExternalID invalid | 自定义id长度不可超过 64 个字符 400 | 2221317 | Department direct sub departments exceed limits | 部门直属子部门数上限为1000 400 | 2221319 | Department name duplicate when creating and updating | 创建和更新时，部门名重复，XX（部门名字）已存在，请使用其他名称 400 | 2221300 | Department common error | 服务异常，请重试 400 | 2221328 | Description invalid | 默认值或多语言值超过100字，请检查并修改。 400 | 2221331 | Custom field value invalid | 自定义字段值不合法，具体参照错误信息 400 | 2221333 | Department name can not contain '/' | 部门名称不能包含"/" 400 | 2221334 | Department ID duplicate | 部门ID已被使用，更换部门ID后重试。 400 | 2224001 | No permission to operate | 无接口权限，请为应用申请接口权限，具体操作参见相关文档。 400 | 2224002 | No permission to operate record | 没有行记录权限，请联系管理员获取行记录权限。 400 | 2224003 | No permission to operate dependent object | 无权限操作相关实体，如父部门、部门Leader，请确认是否有权限操作相关实体。 400 | 2221349 | Department has member, can not disable department | 部门下还有成员，不可停用 400 | 2221350 | Department has child, can not disable department | 部门下还有子部门，不可停用 400 | 2221351 | Department parent is disabled, can not enable | 父部门为停用，不可启用当前部门 400 | 2221352 | Department parent is disabled | 父部门为停用状态，请先启用父部门。