飞书开放平台 Server API 文档

主题

创建部门 ​

本接口用于用于在企业通讯录中创建新部门，支持设置部门名称、父部门、负责人等信息。

Tip: 注意：

  • 只能在当前应用的通讯录授权范围内的部门下创建部门，如果要在根部门下创建子部门，必须拥有全员权限。可以在 开发者后台-应用详情-权限管理中 查看通讯录授权范围。 > - 本接口中支持的user_access_token 默认为管理员用户，将校验管理员管理范围。当用户有多个管理员身份均可创建部门时，管理员管理范围取最大集。管理员权限可查看帮助中心文档：管理员创建管理员角色及分配权限
  • 拥有本接口权限后，即可写入部门信息。但创建部门后仅返回应用有权限的字段数据，如果需要指定字段请按照文档中的描述申请对应权限。
  • 本接口仅对自建应用开放。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/directory/v1/departments
HTTP MethodPOST
接口频率限制5 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可directory:department.create:write 创建部门 directory:department:write 创建、更新、删除部门
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 directory:employee.base.external_id:read 查看员工自定义 ID

请求头 ​

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

查询参数 ​

名称类型必填描述
employee_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - employee_id: 企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。 获取employee_id的方式： - 企业管理员在 管理后台 > 组织架构 > 成员与部门 页面，点击 成员详情，查询员工ID - 通过 批量获取员工列表 的接口，通过手机号或邮箱查询员工ID。
默认值：open_id
当值为 employee_id，字段权限要求： directory:employee.base.external_id:read 查看员工自定义 ID
department_id_typestring否此次调用中使用的部门ID的类型
示例值：open_department_id
可选值有：
- department_id: 用来标识租户内一个唯一的部门 - open_department_id: 用来在具体某个应用中标识一个部门，同一个部门 在不同应用中的 open_department_id 不相同。
默认值：open_department_id

请求体 ​

名称类型必填描述
departmentcreate_department是创建部门
  └ custom_department_idstring否标识租户内一个唯一的部门，支持自定义，未自定义时系统自动生成。ID支持修改。注意： 1. 除需要满足正则规则外，同时不能以od-开头 2. 正则校验：^[a-zA-Z0-9][a-zA-Z0-9_-@.]{0,63}$
示例值："eersdf"
  └ namei18n_text否部门名称，最多可输入 100 字
    └ default_valuestring是默认值
示例值："张三
数据校验规则：
长度范围：1-64 字符"
    └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
示例值：{ "zh_cn": "中文", "ja_jp": "ja_jp_name", "en_us": "en_us_name" }
  └ parent_department_idstring否父部门ID，与department_id_type类型保持一致 。如果父部门为根部门，该参数值为 “0”
示例值："h121900"
  └ leadersdepartment_leader\[\]否部门负责人
数据校验规则：
- 长度范围：0 ～ 20
    └ leader_typeint是部门负责人类型
示例值：1
可选值有：
- 1: 主 - 2: 副
    └ leader_idstring是部门负责人ID，与employee_id_type类型保持一致
示例值："u273y71"
  └ order_weightstring否在上级部门下的排序权重，返回结果按order_weight降序排列
示例值："100"
  └ enabled_statusboolean否是否启用
示例值：true
  └ custom_field_valuescustom_field_value\[\]否部门自定义字段值
数据校验规则：
- 长度范围：0 ～ 100
    └ field_typestring否自定义字段类型
示例值："1"
可选值有：
- 1: 多行文本 - 2: 网页链接 - 3: 枚举选项 - 4: 人员 - 9: 电话 - 10: 多选枚举类型(目前仅支持文本类型) - 11: 人员列表
    └ text_valuei18n_text否文本字段值
      └ default_valuestring是默认值
示例值："张三"
      └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
示例值：{ "zh_cn": "中文", "ja_jp": "ja_jp_name", "en_us": "en_us_name" }
    └ url_valueurl_value否网页链接字段值
      └ link_texti18n_text是网页标题
        └ default_valuestring是默认值
示例值："张三"
        └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
示例值：{"zh_cn":"张三"}
      └ urlstring是移动端网页链接
示例值："https://m.bytedance.com/afnasjfna"
      └ pcurlstring是桌面端网页链接
示例值："http://www.fs.cn"
    └ enum_valueenum_value否枚举字段值
      └ enum_idsstring\[\]是选项结果ID
示例值：["dsa213sa"]
数据校验规则：
- 长度范围：0 ～ 100
      └ enum_typestring是选项类型
示例值："1"
可选值有：
- 1: 文本 - 2: 图片
    └ user_valuesuser_value\[\]否人员字段值
数据校验规则：
- 长度范围：0 ～ 100
      └ idsstring\[\]是人员ID，与employee_id_type类型保持一致
示例值：["asdbjw1s"]
数据校验规则：
- 长度范围：0 ～ 100
    └ phone_valuephone_value否电话字段值
      └ phone_numberstring是电话号
示例值："18812345678"
      └ extension_numberstring否分机号
示例值："234234234
长度范围：0-99字符"
    └ field_keystring否自定义字段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"}]}}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ department_idstring部门ID

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "department_id": "eesdasd"
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4002221305Request parameter error请求参数错误，具体参照错误信息。
4002221306ExternalID repeat租户内自定义ID重复，请更换自定义ID后重试。
4002221307Exceed department limit部门数量超限，请减少部门数量至限制内。
4002221309Department does not exist父部门不存在，请确认父部门ID是否正确。
4002221311Internationalized name duplication部门的英文名称已存在，请使用其他名称 或 部门的日文名称已存在，请使用其他名称
4002221312Exceed department level depth部门层级过深，部门层级上限为25
4002221313ExternalID invalid自定义id长度不可超过 64 个字符
4002221317Department direct sub departments exceed limits部门直属子部门数上限为1000
4002221319Department name duplicate when creating and updating创建和更新时，部门名重复，XX（部门名字）已存在，请使用其他名称
4002221300Department common error服务异常，请重试
4002221328Description invalid默认值或多语言值超过100字，请检查并修改。
4002221331Custom field value invalid自定义字段值不合法，具体参照错误信息
4002221333Department name can not contain '/'部门名称不能包含"/"
4002221334Department ID duplicate部门ID已被使用，更换部门ID后重试。
4002224001No permission to operate无接口权限，请为应用申请接口权限，具体操作参见相关文档。
4002224002No permission to operate record没有行记录权限，请联系管理员获取行记录权限。
4002224003No permission to operate dependent object无权限操作相关实体，如父部门、部门Leader，请确认是否有权限操作相关实体。
4002221349Department has member, can not disable department部门下还有成员，不可停用
4002221350Department has child, can not disable department部门下还有子部门，不可停用
4002221351Department parent is disabled, can not enable父部门为停用，不可启用当前部门
4002221352Department parent is disabled父部门为停用状态，请先启用父部门。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有