跳转到主要内容
POST
人员搜索
按职称、职级、地点或雇主查找人员。也可补全已知人员资料、查询工作邮箱、单独验证邮箱、读取某公司员工资料及实际职称，或在支持时根据 LinkedIn 资料、邮箱、姓名和雇主查询手机号。选择操作，并提供下方必填字段。 所有操作返回规范化 output，以及最后一个 Run 的 id、provider 和生命周期 status。search 和 list_employees 返回 total_matches 及人员列表 output.items[]；enrich、find_email 和 find_phone 在顶层返回同一字段结构的单个人员；verify_email 返回邮箱判断及数据提供商原生状态和标记。invalid、catch-all、disposable 和 unknown 均为有效验证结果，不是未找到。原生输出不在 output 中重复，保留在 Run 中，可通过 GET /v1/runs/:id 读取。数据提供商未报告的值为 null。 分别检查 result_status 和 status：前者为 success、no_result、error 或 pending。charge_usd 为本响应 runs 的总费用，所有 Run 结算前为 null；runs[] 包含各自费用。provider=auto 选择第一家符合条件的数据提供商，仅在 PROVIDER_ERROR、TIMED_OUT 或受理时 503 后尝试下一家；指定数据提供商时不切换。有意重试时复用相同 Idempotency-Key 和执行参数。

​
各操作输出

各操作的规范化字段。enrich 和 find_email 返回与搜索行相同字段的单个人员。原生输出保留在 Run 中，可通过 GET /v1/runs/:id 读取。未报告的值为 null；有效空结果保留操作结构，各字段为 null 或 items 为 []，result_status 为 no_result。姓名、职称和标签按响应方原样保留。自有模型分数带数据提供商名称，如 pdl_likelihood，其他家为 null。
  • search: total_matches, items[]: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • list_employees: total_matches, items[]: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • enrich: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • find_email: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • find_phone: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • verify_email: email, email_status, email_catch_all, email_disposable, email_webmail, hunter_email_score

​
筛选规则

  • PDL 精确匹配 job_titles，因此 “CTO” 不匹配 “Co-founder & CTO”。locations 按子串匹配，因此 “london” 也匹配 “new london, connecticut”。
  • ZoomInfo 没有 founder、owner、partner、head、entry 或 intern 职级，auto 会跳过无法满足这些条件的 ZoomInfo。其 senior 对应整个 “Non Manager” 层级，也包含初级个人贡献者。
  • Hunter search 仅列出 company_domain 下的个人邮箱，不包含 info@ 等角色邮箱。Prospeo enrich 仅返回其持有已验证工作邮箱的人员。通过 Apollo 执行 find_email 时，也可仅提供 linkedin_url；匹配到人员但没有真实邮箱时，视为未找到且不收费。

请求头

​
idempotency-key
string
必填

为每次预期执行生成唯一值，推荐使用 UUID。使用同一个键和执行参数重试，可读取原 Run，避免再次扣费。使用同一个键但修改执行参数会返回 409；修改 task_id 或 metadata 不会更新原 Run。

Minimum string length: 1

请求体

application/json
​
action
enum<string> | null

默认为 search。

  • search：至少提供 job_titles、seniorities、locations、company_domain、keywords 之一。Apollo 和 ZoomInfo 不返回邮箱或电话；PDL 返回完整记录；Hunter 列出 company_domain 下的个人邮箱。
  • list_employees：提供 company_domain。从 LeadMagic 获取最多 100 份员工资料及实际职称，这是样本，不是完整员工名册，不应用职称或地点筛选。
  • enrich：提供 linkedin_url、email，或 full_name 加 company_domain。Prospeo 仅返回其持有已验证工作邮箱的人员。
  • find_email：提供 full_name 和 company_domain；Apollo 也接受仅提供 linkedin_url。Apollo 匹配但未返回真实邮箱时，视为未找到且不收费。
  • verify_email：提供 email。invalid、catch-all、disposable、unknown 判断均为成功答案，不是无结果。使用最终 Run 的 completed_at 作为检查时间。
  • find_phone：LeadMagic 需要 linkedin_url；Prospeo 也接受 email，或 full_name 加 company_domain。仅查询手机号，不发消息或拨号。

筛选条件不会被静默丢弃。auto 会跳过无法应用条件的数据提供商；明确指定时返回 400。

可用选项:
search,
list_employees,
enrich,
find_email,
verify_email,
find_phone
​
provider
enum<string> | null

默认为 auto，按 Glasser 偏好顺序选择第一家符合条件的数据提供商。指定的数据提供商必须支持请求且获得当前 API Key 的允许，不会切换到其他家。可用值见下方。

可用选项:
auto,
apollo,
pdl,
leadmagic,
zoominfo,
hunter,
prospeo
​
job_titles
string[] | null

匹配的职称。PDL 精确匹配每个职称，因此 'CTO' 不匹配 'Co-founder & CTO'。

Required array length: 1 - 20 elements
Required string length: 1 - 200
​
seniorities
enum<string>[] | null

职级，可多选：owner、founder、c_suite、partner、vp、head、director、manager、senior、entry、intern。指定数据提供商没有对应级别时返回 400，自动模式下跳过。ZoomInfo 没有 founder、owner、partner、head、entry 或 intern；其 senior 对应整个 Non Manager 层级，也包含初级个人贡献者。

Required array length: 1 - 11 elements
可用选项:
owner,
founder,
c_suite,
partner,
vp,
head,
director,
manager,
senior,
entry,
intern
​
locations
string[] | null

自由文本地点。PDL 在人员地点名称中按子串匹配，因此 'london' 也匹配 'new london, connecticut'。

Required array length: 1 - 20 elements
Required string length: 1 - 200
​
company_domain
string | null

网站域名，例如 stripe.com。也接受完整 URL，并提取主机名。

Required string length: 3 - 253
​
keywords
string | null
Required string length: 1 - 300
​
full_name
string | null
Required string length: 1 - 200
​
email
string | null

邮箱地址。

Maximum string length: 320
Pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$
​
linkedin_url
string | null

个人 LinkedIn 资料 URL，格式为 linkedin.com/in/，不接受公司页面。

Maximum string length: 2048
Pattern: linkedin\.com\/in\/[^/?#\s]+
​
limit
integer | null

返回条数。请从较少条数开始：路由到的接口可能据此计费。各能力还会进一步限制上限。

必填范围: 1 <= x <= 100
​
task_id
string | null

将相关 Run，包括自动切换产生的 Run，归入同一个 Task。复用稳定字符串，并通过 Task 筛选 Run 列表。

​
metadata

可选追踪字段，随 Run 返回，也可用于筛选。不会发送给数据提供商，也不影响路由、价格或幂等。

  • 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。
  • 值：长度为 1–500 的字符串。
  • user_id：终端用户的不透明 ID，不得使用邮箱或姓名。

无效条目整体丢弃，不截断。请求继续执行，Run 返回实际保存的字段。

响应

成功

​
id
string
必填
​
run_url
string
必填

在控制台打开 Run，需要工作空间成员权限。

​
provider
string
必填
Pattern: ^[a-z0-9][a-z0-9-]*$
​
endpoint
string
必填
Pattern: ^\/.+$
​
endpoint_version
integer
必填
​
status
enum<string>
必填

QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应，包括非 2xx 响应。FAILED 请读取 failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。

可用选项:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
​
failure
object | null
必填

Run 失败原因，仅在 status 为 FAILED 时非 null。

​
input
object
必填
​
output
object
必填

各操作的规范化字段。enrich 和 find_email 返回与搜索行相同字段的单个人员。原生输出保留在 Run 中，可通过 GET /v1/runs/:id 读取。未报告的值为 null；有效空结果保留操作结构，各字段为 null 或 items 为 []，result_status 为 no_result。姓名、职称和标签按响应方原样保留。自有模型分数带数据提供商名称，如 pdl_likelihood，其他家为 null。

  • search: total_matches, items[]: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • list_employees: total_matches, items[]: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • enrich: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • find_email: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • find_phone: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • verify_email: email, email_status, email_catch_all, email_disposable, email_webmail, hunter_email_score
​
provider_response
object | null
必填

仅在 status 为 COMPLETED 时非 null。

  • 2xx 响应：output 为任意结构的数据提供商原生 JSON；正文为空时为 null。
  • 非 2xx 响应：error 包含数据提供商错误正文，output 为 null。

两种正文均会移除敏感字段。

​
charge_usd
string | null
必填

此 Solution 响应所含 runs 的总费用，全部 Run 结算前为 null。每个 Run 保留各自费用；失败也可能收费。

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
​
charge_basis
object | null
必填

单个 Run 的计费依据；多个 Run 汇总时为 null。各项费用请查看 runs[].charge_basis。

​
stoppable
boolean
必填

当前是否可接受停止请求。不保证能在分派前停止 Run。

​
stop_requested_at
string<date-time> | null
必填

请求停止的时间。如果已开始分派，Run 仍可能继续。

​
created_at
string<date-time>
必填

ISO 8601 UTC 时间戳。

​
started_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

​
completed_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

​
task_id
string | null
必填
​
metadata
object
必填

已保存的追踪字段，可用于筛选 Run，不发送给数据提供商，不影响路由、价格或幂等。

  • 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。
  • 值：长度为 1–500 的字符串。
  • user_id：终端用户的不透明 ID，不得使用邮箱或姓名。
​
action
enum<string>
必填
可用选项:
search,
list_employees,
enrich,
find_email,
verify_email,
find_phone
​
result_status
enum<string>
必填

业务交付状态，与 status 中的最终 Run 生命周期独立。no_result 为有效空结果；error 表示数据提供商输出无法交付。

可用选项:
success,
no_result,
error,
pending
​
error
object | null
必填
​
runs
object[]
必填
​
result_url
string
必填

通过认证读取规范化结果和总费用的只读 URL 路径，配合 API 服务地址使用。不创建 Run，也不恢复切换。GET /v1/runs/:id 仍返回原生单个 Run。