# 搜索猎头供应商列表
可根据猎头供应商 ID 列表或关键字、筛选项查询供应商信息。暂不支持获取【邀请中】的供应商列表。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/hire/v1/agencies/batch_query
HTTP Method | POST
接口频率限制 | [10 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 获取招聘猎头信息(hire:agency:readonly)
更新招聘猎头信息(hire:agency)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户 user ID(contact:user.employee_id:readonly)
查看猎头相关用户邮箱(hire:agency.email:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
user_id_type | string | 否 | 用户 ID 类型
**示例值**：open_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)
**默认值**：`open_id`
**当值为 `user_id`，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly)
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 | 系统异常 | 请根据实际报错信息定位问题或联系[技术支持](https://applink.feishu.cn/TLJpeNdW)
400 | 1002002 | 参数错误 | 检查参数是否正确，例如类型，大小