搜索猎头供应商列表
可根据猎头供应商 ID 列表或关键字、筛选项查询供应商信息。暂不支持获取【邀请中】的供应商列表。
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/hire/v1/agencies/batch_query |
| HTTP Method | POST |
| 接口频率限制 | 10 次/秒 |
| 支持的应用类型 | custom,isv |
| 权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可 | hire:agency:readonly 获取招聘猎头信息 hire:agency 更新招聘猎头信息 |
| 字段权限要求 | > Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID hire:agency.email:readonly 查看猎头相关用户邮箱 |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | string | 是 | tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token |
| Content-Type | string | 是 | 固定值："application/json; charset=utf-8" |
查询参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
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？默认值： open_id当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID |
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 示例值：eyJvZmZzZXQiOjEsInRpbWVzdGFtcCI6MTY0MDc2NTYzMjA4OCwiaWQiOm51bGx9 |
page_size | int | 否 | 每页获取记录数量 示例值：10 默认值： 10数据校验规则： - 最大值： 20 |
请求体
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
agency_supplier_id_list | string\[\] | 否 | 猎头供应商 ID 列表，当传递此值，以此值为准，其余查询字段失效 示例值：["7412902352778840358"] 数据校验规则： - 最大长度： 20 |
keyword | string | 否 | 搜索关键字，可传入名称或邮箱 示例值："猎头" |
filter_list | common_filter\[\] | 否 | 筛选项，相同的 Key 仅可传一次，字段取值可查看本文筛选字段说明节 |
└ key | string | 是 | 筛选项 key，使用筛选项查询时必填 示例值："supplier_area" |
└ value_type | int | 是 | 筛选项值类型，使用筛选项查询时必填 示例值：1 可选值有： - 1: 值过滤，填充 value_list 字段 - 2: 范围过滤，填充 range_filter 字段 |
└ value_list | string\[\] | 否 | 筛选项值列表，当value_type为1时必填示例值：["7005471343731164709"] |
└ range_filter | range_filter | 否 | 范围筛选，当value_type为2时必填 |
└ from | string | 否 | 起始值（Unix毫秒时间戳） 示例值："1725951088959" |
└ to | string | 否 | 终止值（Unix毫秒时间戳） 示例值："1725951088960" |
筛选字段说明
| key 取值 | value_type 取值 | 描述 | 需填写字段 | 需填写字段的描述 | 筛选示例 |
|---|---|---|---|---|---|
cooperation_create_time | 2：表示根据范围进行过滤 | 根据合作创建时间过滤 | range_list | 筛选项范围。支持以下字段： - from：起始值 - to：终止值 | json { "filter_list": [ `{ "key": "cooperation_create_time", "value_type": 2, "range_filter": { "from": "1704038400000", "to": "1706716800000" }` } ] } |
cooperation_status | 1：表示值过滤 | 根据合作状态进行过滤 | value_list | 筛选项值的列表，string[] 类型，可选值如下： - 1：正式合作 - 2：试单 - 3：合作终止 - 4：邀请中（暂不支持） | json `{ "filter_list": [ { "key": "cooperation_status", "value_type": 1, "value_list": [ "1", "2" ] }` ] } |
supplier_area | 1：表示值过滤 | 根据猎头地区过滤 | value_list | 筛选项值的列表，string[] 类型，可选值如下： - 1：中国大陆 - 2：非中国大陆 | json `{ "filter_list": [ { "key": "supplier_area", "value_type": 1, "value_list": [ "1" ] }` ] } |
label_id_list | 1：表示值过滤 | 根据猎头标签进行过滤 | value_list | 筛选项值的列表，string[] 类型，填充值为猎头标签 ID，暂不支持获取猎头标签接口，期待后续接口支持。 | json `{ "filter_list": [ { "key": "label_id_list", "value_type": 1, "value_list": [ "7319760942773485572" ] }` ] } |
请求体示例
json
{
"agency_supplier_id_list": [
"7412902352778840358"
],
"keyword": "猎头",
"filter_list": [
{
"key": "supplier_area",
"value_type": 1,
"value_list": [
"7005471343731164709"
],
"range_filter": {
"from": "1725951088959",
"to": "1725951088960"
}
}
]
}响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
code | int | 错误码，非 0 表示失败 |
msg | string | 错误描述 |
data | \- | - |
└ has_more | boolean | 是否还有更多项 |
└ page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token |
└ items | agency_supplier\[\] | 猎头供应商列表 |
└ id | string | 猎头供应商 ID |
└ name | string | 猎头供应商名称 |
└ label_list | agency_supplier_label\[\] | 猎头标签列表 |
└ id | string | 标签 ID |
└ name | i18n | 标签名称 |
└ zh_cn | string | 标签中文名称 |
└ en_us | string | 标签英文名称 |
└ admin_list | agency_supplier_admin\[\] | 管理员列表 |
└ user_id | string | 管理员 ID，与入参user_id_type类型一致 |
└ name | i18n | 管理员名称 |
└ zh_cn | string | 管理员中文名称 |
└ en_us | string | 管理员英文名称 |
└ email | string | 管理员邮箱 字段权限要求： hire:agency.email:readonly 查看猎头相关用户邮箱 |
└ agency_protect_time | agency_supplier_protect_time | 猎头简历保护期 - 候选人在「猎头简历保护期」内入职需支付猎头费用，且保护期内无法被其他猎头公司推荐（猎头公司可重复推荐） |
└ day | int | 保护时长，单位（天） |
└ use_default | boolean | 是否使用统一设置，当为false时代表保护时长（day）由用户自定义设置，否则由招聘系统预设可选值有： - true: 统一设置 - fasle: 非统一设置 |
└ cooperation_create_time | string | 合作创建时间，毫秒时间戳 |
└ cooperation_start_time | string | 合作开始时间，毫秒时间戳 |
└ cooperation_end_time | string | 合作终止时间，毫秒时间戳 |
└ cooperation_status | int | 合作状态 可选值有： - 1: 正式合作 - 2: 试单 - 3: 合作终止 - 4: 邀请中 |
└ invite_email | string | 供应商邮箱 |
└ supplier_area | int | 猎头地区 可选值有： - 1: 中国大陆 - 2: 非中国大陆 |
└ talent_protect_time | agency_supplier_talent_protect_time | 企业自有简历保护期 - 猎头无法推荐在「企业自有简历保护期」内活跃的候选人（「活跃」指在飞书招聘中有「新建人才或投递」、「安排评估、笔试或面试」、「申请 Offer」记录）；猎头无法推荐活跃流程中的候选人 |
└ day | int | 保护时长，单位（天） |
└ use_default | boolean | 是否使用统一设置，当为false时代表保护时长（day）由用户自定义设置，否则由招聘系统预设可选值有： - true: 统一设置 - fasle: 非统一设置 |
└ forever | boolean | 是否永久保护 可选值有： - true: 永久保护 - fasle: 非永久保护 |
响应体示例
json
{
"code": 0,
"msg": "SUCCESS",
"data": {
"has_more": true,
"page_token": "eyJvZmZzZXQiOjEsInRpbWVzdGFtcCI6MTY0MDc2NTYzMjA4OCwiaWQiOm51bGx9",
"items": [
{
"id": "7398493486516799788",
"name": "北极无敌猎头",
"label_list": [
{
"id": "6887469228283299336",
"name": {
"zh_cn": "东方树叶",
"en_us": "oriental Leaves"
}
}
],
"admin_list": [
{
"user_id": "7398493486516799788",
"name": {
"zh_cn": "张三",
"en_us": "ZhangSan"
},
"email": "283xxxx2171813@qq.com"
}
],
"agency_protect_time": {
"day": 180,
"use_default": true
},
"cooperation_create_time": "1639992265035",
"cooperation_start_time": "1639992265035",
"cooperation_end_time": "1639992265035",
"cooperation_status": 1,
"invite_email": "28933718393.qq.com",
"supplier_area": 1,
"talent_protect_time": {
"day": 180,
"use_default": true,
"forever": true
}
}
]
}
}错误码
| HTTP状态码 | 错误码 | 描述 | 排查建议 |
|---|---|---|---|
| 500 | 1002001 | 系统异常 | 请根据实际报错信息定位问题或联系技术支持 |
| 400 | 1002002 | 参数错误 | 检查参数是否正确，例如类型，大小 |