飞书开放平台 Server API 文档

主题

批量查询当前版本的自定义组织信息 ​

根据传入的筛选条件批量查询自定义组织信息。不传任何筛选条件，默认获得该租户下所有的自定义组织数据。

Tip: - 该接口只返回当前生效的自定义组织，未来生效的自定义组织不返回

  • 请求体入参不填写默认为空，不参与筛选
  • 所有筛选项可一起使用，之间为 AND 关系
  • 延迟说明：数据库主从延迟 2s 以内，即：直接创建自定义组织后 2s 内调用此接口可能查询不到数据。
  • 在筛选 ID 和 查询字段对象个数过多时，可能出现超时现象，请减少筛选项和字段对象个数。阻塞性问题请联系技术支持

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/custom_orgs/query
HTTP MethodPOST
接口频率限制5 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:custom_org:read 获取自定义组织信息 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"

查询参数 ​

名称类型必填描述
page_sizeint是分页大小，最大 100
示例值：100
数据校验规则：
- 取值范围：1 ～ 100
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：6891251722631890445
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
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
object_api_namestring是组织类型编码，可在「飞书人事-设置-组织设置」中相应的自定义组织目录下查看
示例值："custom_org_01"
org_fieldsstring\[\]否需要返回的字段列表。字段可填写的列表如下： - names： 组织名称 - code：编码 - parent_id：上级自定义组织 ID - manager_ids：负责人 ID 列表 - description：自定义组织描述 - effective_time：当前版本生效日期 - org_roles：组织角色列表 - active：自定义组织是否启用 - org_id：自定义组织 ID - custom_fields(自定义字段，需传入具体的"custom_api_name") 详细见获取自定义字段列表 ,比如:"shifouleixing_7795__c"
示例值：["names"]
数据校验规则：
- 长度范围：0 ～ 200
org_role_fieldsstring\[\]否需要返回的组织角色授权信息的列表。 - org_role_fields 可选两种值 - 角色key，可以通过页面「飞书人事-设置-组织配置」选择对应自定义组织，「字段配置-字段编码」获取 - 角色ID，可以通过批量获取角色列表 获取，数据为返回数据中的 data.items.id 值。筛选条件data.items.group_type == 3（组织角色），data.items.org_truncation 关联的组织有且仅有一个，data.items.org_truncation.org_key 等于当前查询自定义组织 object_api_name
示例值：["hcm_corehr_xxxx"]
数据校验规则：
- 长度范围：0 ～ 200
org_idsstring\[\]否需要查询的组织 ID 列表。 - ID 为 获取自定义组织返回的 org_id 字段。 - 不传不做 ID 相关限制
示例值：["7140964208476371111"]
数据校验规则：
- 长度范围：0 ～ 200
codestring否只返回和传入编码相同的自定义组织数据。 - 编码为获取自定义组织返回的 code 字段。 - 不传默认不做这个限制
示例值："MDPD00000023"
parent_idstring否只返回 parent_id = 传入值 的自定义组织数据。 - parent_id 为获取自定义组织返回的 org_id 字段。 - 不传默认不做这个限制 - 自定义组织 ID 类型需要为 ==people_corehr_id==
示例值："7140964208476371111"
activeboolean否只返回启用/停用的自定义组织数据。 - 不传默认不做这个限制
示例值：true
need_match_ruleboolean否是否返回匹配规则。 - 为 true 返回 ==match_rule_groups== 字段，否则不返回。
示例值：false

请求体示例 ​

json
{
    "object_api_name": "custom_org_01",
    "org_fields": [
        "names"
    ],
    "org_role_fields": [
        "hcm_corehr_xxxx"
    ],
    "org_ids": [
        "7140964208476371111"
    ],
    "code": "MDPD00000023",
    "parent_id": "7140964208476371111",
    "active": true,
    "need_match_rule": false
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemscustom_org\[\]自定义组织信息列表
    └ object_api_namestring组织类型编码
    └ namesi18n\[\]组织名称
      └ langstring语言，中文值是 zh-CN，英文值是 en-US
      └ valuestring文本内容
    └ codestring编码
    └ parent_idstring上级自定义组织 ID - 若查询的是一级自定义组织，则该字段不展示
    └ manager_idsstring\[\]负责人 ID 列表 - 返回的 ID 类型为 ==employment_id== - 详细信息可通过【搜索员工信息】 或 【批量查询员工】 接口获取
    └ descriptioni18n\[\]自定义组织描述
      └ langstring语言，中文值是 zh-CN，英文值是 en-US
      └ valuestring文本内容
    └ effective_timestring当前版本生效日期 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 00:00:00 - 详情可以参考时间轴介绍
    └ org_rolesorg_role\[\]组织角色列表
      └ api_namestring角色key - 可以通过页面「飞书人事-设置-组织配置」选择对应自定义组织，「字段配置-字段编码」获取
      └ security_group_idstring角色ID - 可以通过批量获取角色列表 获取，数据为返回数据中的 data.items.id 值。筛选条件data.items.group_type == 3（组织角色），data.items.org_truncation 关联的组织有且仅有一个，data.items.org_truncation.org_key 等于当前查询自定义组织 object_api_name
      └ employment_idsstring\[\]直接授权的员工 ID 列表 - 返回的 ID 类型为 ==people_corehr_id== - 详细信息可通过【搜索员工信息】 或 【批量查询员工】 接口获取
      └ inherit_employment_idsstring\[\]由于有上级组织权限而自动获取下级组织权限的员工 ID 列表 - 返回的 ID 类型为 ==people_corehr_id== - 详细信息可通过【搜索员工信息】 或 【批量查询员工】 接口获取
    └ match_rule_groupsmatch_rules\[\]自动匹配的规则组。 - 需要在「飞书人事-设置-组织设置」中打开对应组织类型的自动匹配开关后，此字段才会返回相关值。 - 各个==match_rule_groups==之间是并集关系 - 各个==match_rules==之间是交集关系
      └ match_rulesmatch_rule\[\]匹配规则列表，组内是交集关系
        └ left_valuestring左值
可选值有：
- 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: 包含 - notContains: 不包含
        └ right_valuesstring\[\]右值，填写左值对应的 ID 列表。 - ==department==和==department_hierarchy==：可通过查询单个部门获取详情，ID 类型需要为 ==people_corehr_department_id==。 - ==work_location==和==work_location_hierarchy==：可通过查询单个地点获取详情。 - ==cost_center==和==cost_center_hierarchy==：可通过搜索成本中心信息获取详情。 - ==job==：可通过查询单个职务获取详情。 - ==job_level==：可通过查询单个职级获取详情。 - ==job_family==和==job_family_hierarchy==：可通过查询单个序列获取详情。 - ==employee_type==：可通过查询人员类型获取详情。
    └ activeboolean自定义组织是否启用
    └ org_idstring自定义组织 ID
    └ custom_fieldscustom_field_data\[\]自定义字段类型，详细见获取自定义字段列表
      └ custom_api_namestring自定义字段 API Name，即自定义字段的唯一标识
      └ namecustom_name自定义字段名称
        └ zh_cnstring中文
        └ en_usstring英文
      └ typeint自定义字段类型，详细见获取自定义字段列表
      └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同。如：("123", "123.23", "true", [\"id1\",\"id2\"], "2006-01-02 15:04:05")
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ has_moreboolean是否还有更多项

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "object_api_name": "custom_org_01",
                "names": [
                    {
                        "lang": "zh-CN",
                        "value": "中文示例"
                    }
                ],
                "code": "MDPD00000023",
                "parent_id": "6862995757234914824",
                "manager_ids": [
                    "6862995757234914824"
                ],
                "description": [
                    {
                        "lang": "zh-CN",
                        "value": "中文示例"
                    }
                ],
                "effective_time": "2020-01-01",
                "org_roles": [
                    {
                        "api_name": "hcm_corehr_xxx",
                        "security_group_id": "7034393015968122400",
                        "employment_ids": [
                            "123456789"
                        ],
                        "inherit_employment_ids": [
                            "123456789"
                        ]
                    }
                ],
                "match_rule_groups": [
                    {
                        "match_rules": [
                            {
                                "left_value": "department",
                                "operator": "contains",
                                "right_values": [
                                    "123456789"
                                ]
                            }
                        ]
                    }
                ],
                "active": true,
                "org_id": "6862995757234914824",
                "custom_fields": [
                    {
                        "custom_api_name": "name",
                        "name": {
                            "zh_cn": "自定义姓名",
                            "en_us": "Custom Name"
                        },
                        "type": 1,
                        "value": "\"231\""
                    }
                ]
            }
        ],
        "page_token": "eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=",
        "has_more": true
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001161001param is invalid校验传参是否正确
5031161204Requset timeout联系飞书人事 Oncall
4291161604QPS over limit联系飞书人事 Oncall

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

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