飞书开放平台 Server API 文档

主题

创建自定义组织 ​

使用指定信息创建自定义组织，接口内会做相关规则校验。

Tip: - 每种自定义组织都可以通过此接口创建，不同种自定义组织通过不同 object_api_name 区分。

  • 非必填字段，不传时默认为空。
  • 此接口字段是否必填以【飞书人事-组织配置】为准。建议参照【飞书人事-组织管理-自定义组织-新建】页面来传参

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/custom_orgs
HTTP MethodPOST
接口频率限制5 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用corehr:custom_org:write 读写自定义组织信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

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

查询参数 ​

名称类型必填描述
client_tokenstring否根据client_token是否一致来判断是否为同一请求
示例值：1245464678
数据校验规则：
- 长度范围：0 ～ 128 字符
user_id_typestring否用户 ID 类型
示例值：people_corehr_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？ - people_corehr_id: 以飞书人事的 ID 来识别用户
默认值：people_corehr_id
数据校验规则：
- 长度范围：0 ～ 64 字符
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
object_api_namestring是组织类型编码，可在「飞书人事-设置-组织设置」中相应的自定义组织目录下查看
示例值："custom_org_01"
数据校验规则：
- 长度范围：1 ～ 128 字符
namesi18n\[\]是自定义组织的名称 - 相同上级的自定义组织中英文名称不允许重复。 - 名称不能包含「/」「；」「;」「\」「'」字符。
数据校验规则：
- 长度范围：0 ～ 5
  └ langstring是名称信息的语言，中文用 zh-CN，英文用 en-US
示例值："zh-CN"
  └ valuestring是名称信息的内容。
示例值："飞书人事"
codestring否自定义组织编码 (不能与其他记录的编码重复) - 开启自动编码时，如果不传值会自动生成编码，否则以传入值为准 - 未开启自动编码时，不传值不会自动生成编码
示例值："000001（格式和配置的匹配规则相关）"
数据校验规则：
- 长度范围：0 ～ 128 字符
parent_idstring否上级自定义组织 ID - 上级自定义组织的状态必须是启用的。 - 可从 批量查询自定义组织的 org_id 字段中获取。
示例值："6862995757234914824"
manager_idsstring\[\]否负责人 ID 列表。 - 详细信息可通过【搜索员工信息】 或 【批量查询员工】 接口获取，ID 为返回值中的 ==employment_id==
示例值：["6862995757234914824"]
数据校验规则：
- 长度范围：0 ～ 100
descriptioni18n\[\]否自定义组织描述
数据校验规则：
- 长度范围：0 ～ 5
  └ langstring是语言, 中文用 zh-CN ，英文用 en-US
示例值："zh-CN"
  └ valuestring是文本内容
示例值："中文示例"
effective_timestring是自定义组织生效时间 - 填写格式： YYYY-MM-DD - 系统默认为填写日期当天的 00:00:00 生效 - 该接口只支持到最小单位为日 - 日期范围要求:1900-01-01 ～ 9999-12-31
示例值："2020-01-01"
数据校验规则：
- 长度范围：10 ～ 10 字符 - 正则校验：`^((([0-9]{3}[1-9]
org_rolesorg_role_update\[\]否自动给「按自定义组织授权的角色」授权
数据校验规则：
- 长度范围：0 ～ 64
  └ api_namestring否角色key - api_name、security_group_id必须填一个 - 可以通过页面「飞书人事-设置-组织配置」选择对应自定义组织，「字段配置-字段编码」获取
示例值："hcm_corehr_xxxxxx"
  └ security_group_idstring否角色ID - api_name、security_group_id必须填一个 - 可以通过批量获取角色列表 获取，数据为返回数据中的 data.items.id 值。筛选条件data.items.group_type == 3（组织角色），data.items.org_truncation 关联的组织有且仅有一个，data.items.org_truncation.org_key 等于当前查询自定义组织 object_api_name
示例值："7034393015968122400"
  └ employment_idsstring\[\]否被授权的员工 ID 列表 - 详细信息可通过【搜索员工信息】 或 【批量查询员工】 接口获取
示例值：["6862995757234914824"]
数据校验规则：
- 长度范围：0 ～ 100
match_rule_groupsmatch_rules\[\]否自动匹配的规则组。 - 需要在「飞书人事-设置-组织设置」中打开对应组织类型的自动匹配开关后，才可以使用匹配规则组字段。 - 各个==match_rule_groups==之间是并集关系 - 各个==match_rules==之间是交集关系
数据校验规则：
- 长度范围：0 ～ 16
  └ match_rulesmatch_rule\[\]否匹配规则列表，组内是交集关系
数据校验规则：
- 长度范围：0 ～ 64
    └ left_valuestring是左值
示例值："department"
可选值有：
- department: 部门 - department_hierarchy: 部门（含下级） - work_location: 工作地点 - work_location_hierarchy: 工作地点（含下级） - cost_center: 成本中心 - cost_center_hierarchy: 成本中心（含下级） - job: 职务 - job_level: 职级 - job_family: 序列 - job_family_hierarchy: 序列（含下级） - employee_type: 人员类型
    └ operatorstring是操作符
示例值："contains"
可选值有：
- contains: 包含 - notContains: 不包含
    └ right_valuesstring\[\]否右值，填写左值对应的 ID 列表。 - ==department==和==department_hierarchy==：详细 ID 可通过查询单个部门接口获得，ID 类型需要为 ==people_corehr_department_id==。 - ==work_location==和==work_location_hierarchy==：详细 ID 可通过查询单个地点接口获得。 - ==cost_center==和==cost_center_hierarchy==：详细 ID 可通过搜索成本中心信息接口获得。 - ==job==：详细 ID 可通过查询单个职务接口获得。 - ==job_level==：详细 ID 可通过查询单个职级接口获得。 - ==job_family==和==job_family_hierarchy==：详细 ID 可通过查询单个序列接口获得。 - ==employee_type==：详细 ID 可通过查询人员类型接口获得。
示例值：["6862995757234914824"]
数据校验规则：
- 长度范围：0 ～ 10000
custom_fieldscustom_field_data\[\]否自定义字段类型，详细见获取自定义字段列表
数据校验规则：
- 长度范围：0 ～ 200
  └ custom_api_namestring是自定义字段 API Name，即自定义字段的唯一标识
示例值："name"
  └ valuestring是字段值，为 JSON 转义后的字符串。
注意：具体传值方式参见获取自定义字段的元数据
示例值：""231""

请求体示例 ​

json
{
    "object_api_name": "custom_org_01",
    "names": [
        {
            "lang": "zh-CN",
            "value": "飞书人事"
        }
    ],
    "code": "000001（格式和配置的匹配规则相关）",
    "parent_id": "6862995757234914824",
    "manager_ids": [
        "6862995757234914824"
    ],
    "description": [
        {
            "lang": "zh-CN",
            "value": "中文示例"
        }
    ],
    "effective_time": "2020-01-01",
    "org_roles": [
        {
            "api_name": "hcm_corehr_xxxxxx",
            "security_group_id": "7034393015968122400",
            "employment_ids": [
                "6862995757234914824"
            ]
        }
    ],
    "match_rule_groups": [
        {
            "match_rules": [
                {
                    "left_value": "department",
                    "operator": "contains",
                    "right_values": [
                        "6862995757234914824"
                    ]
                }
            ]
        }
    ],
    "custom_fields": [
        {
            "custom_api_name": "name",
            "value": "\"231\""
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ org_idstring自定义组织的 ID

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "org_id": "6862995757234914824"
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001160263The code already exists检查编码是否正确
4001160255Parent organization hasn't taken effect on effective date检查上级组织是否生效
4001160256Parent organization will be deactivated on or after this effective date检查上级是否即将停用
4001160264This operation will make the relationship between the superior and the subordinate into a ring检查检查上下级之间是否成环
4001161603Name already exists检查名称是否与相同上级组织下的其他同级组织重名
5031161204Requset timeout联系飞书人事 Oncall 获取技术支持
4291161604QPS over limit联系飞书人事 Oncall 获取技术支持

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

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