搜索部门信息

该接口支持通过部门id、上级部门ID、部门负责人、名称、编码字段批量搜索当天的部门详情信息，包括部门包含的名称、描述、启用状态等。

Warning: 延迟说明：搜索同步延迟 10s 以内，即：直接创建部门后10s内调用此接口可能查询不到数据。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/corehr/v2/departments/search
HTTP Method	POST
接口频率限制	100 次/分钟
支持的应用类型	custom,isv
权限要求调用该 API 所需的权限。开启其中任意一项权限即可调用开启任一权限即可	`corehr:department:read` 获取部门信息 `corehr:department:write` 读写部门信息
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 `corehr:department.cost_center_id:read` 获取部门成本中心字段信息 `corehr:department.custom_fields:read` 获取部门自定义字段 `corehr:department.manager:read` 获取部门负责人信息 `corehr:department.organize:read` 获取部门组织架构信息 `contact:user.employee_id:readonly` 获取用户 user ID

请求头

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

查询参数

名称	类型	必填	描述
`page_size`	`int`	是	分页大小示例值：100 数据校验规则： - 取值范围：`1` ～ `100`
`page_token`	`string`	否	分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果示例值：6891251722631890445
`user_id_type`	`string`	否	用户 ID 类型示例值：open_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 来识别用户默认值：`open_id` 当值为 `user_id`，字段权限要求： `contact:user.employee_id:readonly` 获取用户 user ID
`department_id_type`	`string`	否	此次调用中使用的部门 ID 类型示例值：open_department_id 可选值有： - `open_department_id`: 【飞书】用来在具体某个应用中标识一个部门，同一个department_id 在不同应用中的 open_department_id 相同。 - `department_id`: 【飞书】用来标识租户内一个唯一的部门。 - `people_corehr_department_id`: 【飞书人事】用来标识「飞书人事」中的部门。默认值：`open_department_id`

请求体

名称	类型	必填	描述
`active`	`boolean`	否	该部门是否启用，true为启用，false为停用 - 如果传空则所有启用状态数据都返回示例值：true
`get_all_children`	`boolean`	否	当通过上级部门 ID 查询时，填写 true 返回所有子部门，填写 false 只返回直接下级部门 - 默认为false 示例值：false
`manager_list`	`string\[\]`	否	部门负责人 ID 列表 - 详细信息可通过【搜索员工信息】或【批量查询员工】接口获取 - 传非空值返回指定部门负责人的部门，传空值则不加该筛选条件示例值：["7094136522860922112"] 数据校验规则： - 最大长度：`100`
`department_id_list`	`string\[\]`	否	部门 ID列表，用来做条件筛选 - 传非空值返回指定部门ID，传空值则不加该筛选条件 - 一次性最多传入100个部门ID 示例值：["7094136522860922111"]
`name_list`	`string\[\]`	否	部门名称列表，需精确匹配，用于筛选条件 - 传非空值则返回指定部门名称的部门，传空值则不加该筛选条件示例值：["后端研发部"]
`parent_department_id`	`string`	否	上级部门 ID - 可通过批量查询部门V2 或者搜索部门信息获取详情 - 传非空值返回指定上级部门ID的子部门，传空值则不加该筛选条件示例值："7094136522860922222"
`code_list`	`string\[\]`	否	部门编码列表 - 传非空值返回指定编码的部门，传空值则不加该筛选条件示例值：["D00000123"]
`fields`	`string\[\]`	否	返回数据的字段列表，如果传空只返回部门id，可选值： - version_id：当前版本ID - sub_type：部门类型 - manager：负责人 - is_root：是否根部门 - is_confidential：是否保密 - effective_date：当前版本生效日期 - expiration_date：当前版本失效日期 - department_name：部门名称 - parent_department_id：上级部门ID - tree_order：树形排序 - list_order：列表排序 - code：部门编码 - active：是否启用 - description：部门描述 - custom_fields：自定义字段 - staffing_model：岗职务模式 - cost_center_id：部门默认成本中心 - created_time：创建时间(版本创建时间) - updated_time：更新时间 - created_by：创建人 - updated_by：更新人 - record_created_time：记录创建时间(第一个版本的创建时间) - record_updated_time：记录更新时间 - record_created_by：记录创建人 - record_updated_by：记录更新人示例值：["department_name"]

请求体示例

json

{
    "active": true,
    "get_all_children": false,
    "manager_list": [
        "7094136522860922112"
    ],
    "department_id_list": [
        "7094136522860922111"
    ],
    "name_list": [
        "后端研发部"
    ],
    "parent_department_id": "7094136522860922222",
    "code_list": [
        "D00000123"
    ],
    "fields": [
        "department_name"
    ]
}

响应

响应体

名称	类型	描述
`code`	`int`	错误码，非 0 表示失败
`msg`	`string`	错误描述
`data`	`\-`	-
└ `items`	`department\[\]`	查询的部门信息
└ `id`	`string`	部门 ID
└ `version_id`	`string`	部门记录版本 ID
└ `department_name`	`i18n\[\]`	部门名称
└ `lang`	`string`	语言，中文用zh-CN，英文用en-US
└ `value`	`string`	文本内容
└ `sub_type`	`enum`	部门类型，枚举值 api_name 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name = "department" - custom_api_name = "subtype"
└ `enum_name`	`string`	枚举值
└ `display`	`i18n\[\]`	枚举多语展示
└ `lang`	`string`	语言，中文用zh-CN，英文用en-US
└ `value`	`string`	文本内容
└ `parent_department_id`	`string`	上级部门 ID - 可通过批量查询部门V2 或者搜索部门信息获取详情字段权限要求： `corehr:department.organize:read` 获取部门组织架构信息
└ `manager`	`string`	部门负责人雇佣 ID - 详细信息可通过【搜索员工信息】或【批量查询员工】接口获取字段权限要求： `corehr:department.manager:read` 获取部门负责人信息
└ `tree_order`	`string`	树形排序，代表同层级的部门排序序号 - 数据类型为字符串，实际按数值大小排序，数值越小，同层级部门展示越靠前；仅对同一父部门下的直接子部门生效 - 数值生成规则： - 编号长度由同层级部门数量动态决定：同层级部门≤10 个为 6 位编号，10~20 个为 7 位编号，超过 100 个统一为 16 位编号，以此类推 - 新建部门时系统自动赋值：同层级下一个新部门编号，会在上一个部门编号基础上按固定数值自动累加；例如 6 位编号每次固定加 1000，7 位编号每次固定加 10000 - 重排触发：当同层级部门数量超出当前编号长度可容纳范围，或多次拖拽排序无法正常插入位置时，会触发同层级编号全局重新编排；所有部门编号会按新的长度和累加规则重新生成，数值可能出现明显变大 - 当同一父部门下的子部门数量超过 1000 个时，系统在维护排序编号时可能出现异常问题。 - 更新时机： - 创建部门场景tree_order不会实时生成，10分钟内更新完毕 - 在页面拖动部门排序时tree_order可以实时生成 - 变更部门上级时，会清空tree_order，并触发重算list_order和tree_order，10分钟内更新完毕（list_order由部门上级路径的所有tree_order用“-”拼接生成）
└ `list_order`	`string`	列表排序，代表所有部门的混排序号，为该部门上级路径上所有tree_order用“-”拼接。 - 该字段在新建/更新场景非立即更新，10分钟后会延迟更新 - 由于list_order变更会导致部门变更接口产生大量事件，因此事件接口不会针对该字段同步变更事件，如果有需求订阅请联系Oncall单独开启。 - 同层部门（相同上级）数量超过1000时，该字段不再更新
└ `code`	`string`	编码
└ `is_root`	`boolean`	是否根部门
└ `is_confidential`	`boolean`	是否保密（该功能暂不支持，可以忽略）
└ `effective_date`	`string`	当前版本生效日期 - 返回格式：YYYY-MM-DD（最小单位到日） - 日期范围:1900-01-01～9999-12-31
└ `expiration_date`	`string`	当前版本失效日期 - 返回格式：YYYY-MM-DD（最小单位到日） - 日期范围:1900-01-01～9999-12-31
└ `active`	`boolean`	是否启用
└ `description`	`i18n\[\]`	描述
└ `lang`	`string`	语言，中文用zh-CN，英文用en-US
└ `value`	`string`	文本内容
└ `custom_fields`	`custom_field_data\[\]`	自定义字段类型，详细见获取自定义字段列表字段权限要求： `corehr:department.custom_fields:read` 获取部门自定义字段
└ `custom_api_name`	`string`	自定义字段 apiname，即自定义字段的唯一标识
└ `name`	`custom_name`	自定义字段名称
└ `zh_cn`	`string`	中文
└ `en_us`	`string`	英文
└ `type`	`int`	自定义字段类型，详细见获取自定义字段列表
└ `value`	`string`	字段值，是 json 转义后的字符串，根据元数据定义不同，字段格式不同（如 123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05"）
└ `staffing_model`	`enum`	岗职管理模式 - 详细枚举类型请查看枚举场景中关于staffing_model定义
└ `enum_name`	`string`	枚举值
└ `display`	`i18n\[\]`	枚举多语展示
└ `lang`	`string`	语言，中文用zh-CN，英文用en-US
└ `value`	`string`	文本内容
└ `cost_center_id`	`string`	成本中心id 字段权限要求： `corehr:department.cost_center_id:read` 获取部门成本中心字段信息
└ `created_time`	`string`	创建时间(版本创建时间)
└ `updated_time`	`string`	更新时间
└ `created_by`	`string`	创建人
└ `updated_by`	`string`	更新人
└ `record_created_time`	`string`	记录创建时间(第一个版本的创建时间)
└ `record_updated_time`	`string`	记录更新时间
└ `record_created_by`	`string`	记录创建人
└ `record_updated_by`	`string`	记录更新人
└ `page_token`	`string`	分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
└ `has_more`	`boolean`	是否还有更多项

响应体示例

json

{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "id": "4719456877659520852",
                "version_id": "6890452208593372611",
                "department_name": [
                    {
                        "lang": "zh-CN",
                        "value": "中文示例"
                    }
                ],
                "sub_type": {
                    "enum_name": "phone_type",
                    "display": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "parent_department_id": "4719456877659520111",
                "manager": "6893013238632416777",
                "tree_order": "001000",
                "list_order": "001000-001000",
                "code": "D00000456",
                "is_root": false,
                "is_confidential": false,
                "effective_date": "2020-05-01",
                "expiration_date": "2020-05-02",
                "active": true,
                "description": [
                    {
                        "lang": "zh-CN",
                        "value": "中文示例"
                    }
                ],
                "custom_fields": [
                    {
                        "custom_api_name": "name",
                        "name": {
                            "zh_cn": "自定义姓名",
                            "en_us": "Custom Name"
                        },
                        "type": 1,
                        "value": "\"231\""
                    }
                ],
                "staffing_model": {
                    "enum_name": "position",
                    "display": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "cost_center_id": "7142384817131652652",
                "created_time": "2020-05-01 00:00:00",
                "updated_time": "2020-05-02 00:00:00",
                "created_by": "6893013238632416777",
                "updated_by": "6893013238632416777",
                "record_created_time": "2020-05-01 00:00:00",
                "record_updated_time": "2020-05-02 00:00:00",
                "record_created_by": "6893013238632416777",
                "record_updated_by": "6893013238632416777"
            }
        ],
        "page_token": "eyJldV9uYyI6IlswLFwiNjk2MTI4Njg0NjA5Mzc4ODY4MC03MjExMDM0ODcxMjA3OTUzOTc1XCJdIn0",
        "has_more": true
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	1160102	请求参数错误	请确认请求参数是否满足接口要求
403	1160103	No permission	操作无权限，请确认查询条件是否满足权限要求
503	1161204	内部接口超时	接口超时，可尝试重试。如果无法解决可以联系飞书人事技术支持
429	1161604	内部接口频控	接口请求次数超过接口频率限制，可尝试降低请求频率

事件

事件

员工兼职

员工国际派遣

职位数据事件

事件

事件

事件

事件

事件

事件

事件

成本中心 · version

事件

事件

事件

事件

地点 · address

事件

事件

搜索部门信息 ​

请求 ​

请求头 ​

查询参数 ​

请求体 ​

请求体示例 ​

响应 ​

响应体 ​

响应体示例 ​

错误码 ​

搜索部门信息

请求

请求头

查询参数

请求体

请求体示例

响应

响应体

响应体示例

错误码