> ## Documentation Index
> Fetch the complete documentation index at: https://glasser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 人员搜索

> 查找人员、补全资料、查询工作邮箱和手机号，或验证邮箱。选择操作并提供必填字段。

按职称、职级、地点或雇主查找人员。也可补全已知人员资料、查询工作邮箱、单独验证邮箱、读取某公司员工资料及实际职称，或在支持时根据 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

```json
{
  "action": "find_email",
  "provider": "hunter",
  "status": "COMPLETED",
  "result_status": "success",
  "output": {
    "name": null, "first_name": "Avery", "last_name": "Example", "job_title": null,
    "email": "example@stripe.com", "email_status": "valid", "email_catch_all": true, "email_source": "generated",
    "company_name": "Stripe", "company_domain": "stripe.com", "hunter_email_score": 80, "…": "other fields null"
  },
  "charge_usd": "0.0245",
  "runs": [{ "provider": "hunter", "status": "COMPLETED", "charge_usd": "0.0245" }],
  "result_url": "/v1/solutions/gtm/people_search/result?token=…"
}
```

## 筛选规则

* 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`；匹配到人员但没有真实邮箱时，视为未找到且不收费。


## OpenAPI

````yaml /openapi.zh.json post /v1/solutions/gtm/people_search
openapi: 3.1.0
info:
  title: Glasser
  version: 0.0.1
  description: 一个 API Key，无需合同，按次付费，即可调用批量采购的付费 API。每个响应包含 x-request-id；所有错误正文采用统一结构。
servers:
  - url: https://api.glasser.ai
security: []
tags:
  - name: Solutions
  - name: Endpoints
  - name: Runs
  - name: Balance
paths:
  /v1/solutions/gtm/people_search:
    post:
      tags:
        - Solutions
      summary: 人员搜索
      description: >-
        按职称、职级、地点或雇主查找人员。也可补全已知人员资料、查询工作邮箱、单独验证邮箱、读取某公司员工资料及实际职称，或在支持时根据
        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 和执行参数。
      operationId: gtm-people-search
      parameters:
        - name: idempotency-key
          in: header
          schema:
            type: string
            minLength: 1
            description: >-
              为每次预期执行生成唯一值，推荐使用 UUID。使用同一个键和执行参数重试，可读取原
              Run，避免再次扣费。使用同一个键但修改执行参数会返回 409；修改 task_id 或 metadata 不会更新原 Run。
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  anyOf:
                    - type: string
                      enum:
                        - search
                        - list_employees
                        - enrich
                        - find_email
                        - verify_email
                        - find_phone
                      description: >-
                        默认为 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。
                    - type: 'null'
                provider:
                  anyOf:
                    - type: string
                      enum:
                        - auto
                        - apollo
                        - pdl
                        - leadmagic
                        - zoominfo
                        - hunter
                        - prospeo
                      description: >-
                        默认为 auto，按 Glasser
                        偏好顺序选择第一家符合条件的数据提供商。指定的数据提供商必须支持请求且获得当前 API Key
                        的允许，不会切换到其他家。可用值见下方。
                    - type: 'null'
                job_titles:
                  anyOf:
                    - type: array
                      items:
                        type: string
                        minLength: 1
                        maxLength: 200
                      minItems: 1
                      maxItems: 20
                      description: 匹配的职称。PDL 精确匹配每个职称，因此 'CTO' 不匹配 'Co-founder & CTO'。
                    - type: 'null'
                seniorities:
                  anyOf:
                    - type: array
                      items:
                        type: string
                        enum:
                          - owner
                          - founder
                          - c_suite
                          - partner
                          - vp
                          - head
                          - director
                          - manager
                          - senior
                          - entry
                          - intern
                      minItems: 1
                      maxItems: 11
                      description: >-
                        职级，可多选：owner、founder、c_suite、partner、vp、head、director、manager、senior、entry、intern。指定数据提供商没有对应级别时返回
                        400，自动模式下跳过。ZoomInfo 没有 founder、owner、partner、head、entry
                        或 intern；其 senior 对应整个 Non Manager 层级，也包含初级个人贡献者。
                    - type: 'null'
                locations:
                  anyOf:
                    - type: array
                      items:
                        type: string
                        minLength: 1
                        maxLength: 200
                      minItems: 1
                      maxItems: 20
                      description: >-
                        自由文本地点。PDL 在人员地点名称中按子串匹配，因此 'london' 也匹配 'new london,
                        connecticut'。
                    - type: 'null'
                company_domain:
                  anyOf:
                    - type: string
                      minLength: 3
                      maxLength: 253
                      description: 网站域名，例如 stripe.com。也接受完整 URL，并提取主机名。
                    - type: 'null'
                keywords:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 300
                    - type: 'null'
                full_name:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 200
                    - type: 'null'
                email:
                  anyOf:
                    - type: string
                      maxLength: 320
                      pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$
                      description: 邮箱地址。
                    - type: 'null'
                linkedin_url:
                  anyOf:
                    - type: string
                      maxLength: 2048
                      pattern: linkedin\.com\/in\/[^/?#\s]+
                      description: 个人 LinkedIn 资料 URL，格式为 linkedin.com/in/<slug>，不接受公司页面。
                    - type: 'null'
                limit:
                  anyOf:
                    - type: integer
                      minimum: 1
                      maximum: 100
                      description: 返回条数。请从较少条数开始：路由到的接口可能据此计费。各能力还会进一步限制上限。
                    - type: 'null'
                task_id:
                  anyOf:
                    - type: string
                      description: >-
                        将相关 Run，包括自动切换产生的 Run，归入同一个 Task。复用稳定字符串，并通过 Task 筛选 Run
                        列表。
                    - type: 'null'
                metadata:
                  anyOf:
                    - anyOf:
                        - type: object
                          additionalProperties:
                            type: string
                            minLength: 1
                            maxLength: 500
                          maxProperties: 20
                          propertyNames:
                            type: string
                            pattern: ^[a-z][a-z0-9_]{0,39}$
                        - {}
                      description: |-
                        可选追踪字段，随 Run 返回，也可用于筛选。不会发送给数据提供商，也不影响路由、价格或幂等。

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

                        无效条目整体丢弃，不截断。请求继续执行，Run 返回实际保存的字段。
                    - type: 'null'
              additionalProperties: false
        required: true
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PeopleSearchResult'
        '202':
          description: 成功
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PeopleSearchResult'
        '400':
          description: ValidationFailed | IdempotencyKeyRequired
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
                  - $ref: '#/components/schemas/IdempotencyKeyRequiredEncoded'
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedEncoded'
        '402':
          description: InsufficientBalance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientBalanceEncoded'
        '403':
          description: EndpointNotPermitted | Forbidden
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/EndpointNotPermittedEncoded'
                  - $ref: '#/components/schemas/ForbiddenEncoded'
        '409':
          description: IdempotencyConflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdempotencyConflictEncoded'
        '429':
          description: RateLimited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedEncoded'
        '503':
          description: ServiceUnavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableEncoded'
      security:
        - bearer: []
components:
  schemas:
    PeopleSearchResult:
      type: object
      properties:
        id:
          type: string
        run_url:
          type: string
          description: 在控制台打开 Run，需要工作空间成员权限。
        provider:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]*$
        endpoint:
          type: string
          pattern: ^\/.+$
        endpoint_version:
          type: integer
          exclusiveMinimum: 0
        status:
          type: string
          enum:
            - QUEUED
            - RUNNING
            - COMPLETED
            - FAILED
            - STOPPED
          description: >-
            QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应，包括非 2xx 响应。FAILED 请读取
            failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。
        failure:
          anyOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - TIMED_OUT
                    - INTERNAL
                message:
                  type: string
              required:
                - kind
                - message
              additionalProperties: false
            - type: 'null'
          description: Run 失败原因，仅在 status 为 FAILED 时非 null。
        input:
          type: object
        output:
          anyOf:
            - anyOf:
                - type: object
                  properties:
                    total_matches:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                      description: 数据提供商整个数据集中符合条件的人数，不仅是当前页；仅提供当前页数量时为 null，例如 LeadMagic。
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 数据提供商原样报告的全名，PDL 为小写。仅提供名和姓时为 null，不拼接。
                          first_name:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 数据提供商报告的名。
                          last_name:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 数据提供商报告的姓；被遮蔽时为 null，例如 Apollo search。
                          job_title:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 数据提供商报告的当前职称。
                          seniority:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              响应方自身词汇中的职级，例如 Apollo founder、PDL cxo、LeadMagic
                              C-Team、Hunter executive。不同于请求中的 seniorities
                              词汇，不能跨家比较，请检查 provider。返回多个值时取第一个。
                          department:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 响应方自身词汇中的部门或职能，返回多个值时取第一个。
                          headline:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 个人资料标题，即 LinkedIn 的职称行。
                          linkedin_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: LinkedIn 个人资料 URL；数据提供商省略协议时添加 https://。
                          city:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 人员所在城市。
                          region:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 人员所在州或地区。
                          country:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 人员所在国家的英文展示名称，不是代码。
                          country_code:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 人员所在国家的 ISO 3166-1 alpha-2 代码。
                          email:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 数据提供商报告的工作邮箱。PDL 只使用 work_email，其他邮箱保留在 Run 中。
                          email_status:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              响应方自身邮箱验证标签，例如 Apollo verified、Prospeo
                              VERIFIED、Hunter 和 LeadMagic
                              valid。各家验证方式不同，标签不可直接比较；结合 email_catch_all 和
                              email_source 阅读。
                          email_catch_all:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                            description: >-
                              数据提供商报告邮箱域接受所有地址时为 true，因此无法通过邮箱检测确认此地址。例如 Hunter
                              accept_all、Apollo email_domain_catchall。
                          email_source:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              Hunter 获取邮箱的方式：found 表示在网页发现，generated
                              表示按域名邮箱模式生成；其他数据提供商为 null。
                          phone:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 数据提供商报告的电话号码，遮蔽号码不返回。
                          company_name:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 数据提供商报告的当前雇主。
                          company_domain:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 当前雇主域名，不含 www. 和端口。
                          company_linkedin_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 当前雇主的 LinkedIn 公司页面 URL。
                          apollo_match_confidence:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              Apollo 对记录与输入匹配的置信度：high、medium、low 或
                              none；其他数据提供商为 null。
                          pdl_likelihood:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                            description: >-
                              People Data Labs 对记录与输入匹配程度的 1–10 分数；其他数据提供商为
                              null。
                          hunter_email_score:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                            description: >-
                              Hunter 对邮箱的 0–100 置信度，来自 email-finder score 或
                              domain-search confidence；其他数据提供商为 null。
                          zoominfo_accuracy_score:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                            description: ZoomInfo 的 0–100 联系信息准确度分数；其他数据提供商为 null。
                        required:
                          - 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
                        additionalProperties: false
                  required:
                    - total_matches
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    email:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 数据提供商返回的邮箱地址。
                    email_status:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 数据提供商自身的可投递判断。unknown 和 catch-all 不代表已验证可投递。
                    email_catch_all:
                      anyOf:
                        - type: boolean
                        - type: 'null'
                      description: 数据提供商是否报告为 catch-all 域。
                    email_disposable:
                      anyOf:
                        - type: boolean
                        - type: 'null'
                      description: 数据提供商是否报告为一次性邮箱。
                    email_webmail:
                      anyOf:
                        - type: boolean
                        - type: 'null'
                      description: 数据提供商是否报告为免费网页邮箱。
                    hunter_email_score:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                      description: Hunter 自身的 0–100 置信度分数；其他数据提供商为 null。
                  required:
                    - email
                    - email_status
                    - email_catch_all
                    - email_disposable
                    - email_webmail
                    - hunter_email_score
                  additionalProperties: false
                - type: object
                  properties:
                    name:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 数据提供商原样报告的全名，PDL 为小写。仅提供名和姓时为 null，不拼接。
                    first_name:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 数据提供商报告的名。
                    last_name:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 数据提供商报告的姓；被遮蔽时为 null，例如 Apollo search。
                    job_title:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 数据提供商报告的当前职称。
                    seniority:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        响应方自身词汇中的职级，例如 Apollo founder、PDL cxo、LeadMagic
                        C-Team、Hunter executive。不同于请求中的 seniorities
                        词汇，不能跨家比较，请检查 provider。返回多个值时取第一个。
                    department:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 响应方自身词汇中的部门或职能，返回多个值时取第一个。
                    headline:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 个人资料标题，即 LinkedIn 的职称行。
                    linkedin_url:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: LinkedIn 个人资料 URL；数据提供商省略协议时添加 https://。
                    city:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 人员所在城市。
                    region:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 人员所在州或地区。
                    country:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 人员所在国家的英文展示名称，不是代码。
                    country_code:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 人员所在国家的 ISO 3166-1 alpha-2 代码。
                    email:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 数据提供商报告的工作邮箱。PDL 只使用 work_email，其他邮箱保留在 Run 中。
                    email_status:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        响应方自身邮箱验证标签，例如 Apollo verified、Prospeo VERIFIED、Hunter 和
                        LeadMagic valid。各家验证方式不同，标签不可直接比较；结合 email_catch_all 和
                        email_source 阅读。
                    email_catch_all:
                      anyOf:
                        - type: boolean
                        - type: 'null'
                      description: >-
                        数据提供商报告邮箱域接受所有地址时为 true，因此无法通过邮箱检测确认此地址。例如 Hunter
                        accept_all、Apollo email_domain_catchall。
                    email_source:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        Hunter 获取邮箱的方式：found 表示在网页发现，generated
                        表示按域名邮箱模式生成；其他数据提供商为 null。
                    phone:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 数据提供商报告的电话号码，遮蔽号码不返回。
                    company_name:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 数据提供商报告的当前雇主。
                    company_domain:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 当前雇主域名，不含 www. 和端口。
                    company_linkedin_url:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 当前雇主的 LinkedIn 公司页面 URL。
                    apollo_match_confidence:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        Apollo 对记录与输入匹配的置信度：high、medium、low 或 none；其他数据提供商为
                        null。
                    pdl_likelihood:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                      description: People Data Labs 对记录与输入匹配程度的 1–10 分数；其他数据提供商为 null。
                    hunter_email_score:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                      description: >-
                        Hunter 对邮箱的 0–100 置信度，来自 email-finder score 或
                        domain-search confidence；其他数据提供商为 null。
                    zoominfo_accuracy_score:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                      description: ZoomInfo 的 0–100 联系信息准确度分数；其他数据提供商为 null。
                  required:
                    - 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
                  additionalProperties: false
            - type: 'null'
          description: >-
            各操作的规范化字段。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:
          anyOf:
            - type: object
              properties:
                http_status:
                  type: integer
                  minimum: 100
                  maximum: 599
                  description: 数据提供商返回的 HTTP 状态，即使 Run 为 COMPLETED 也应检查。
                error:
                  anyOf:
                    - {}
                    - type: 'null'
              required:
                - http_status
              additionalProperties: false
            - type: 'null'
          description: |-
            仅在 status 为 COMPLETED 时非 null。

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

            两种正文均会移除敏感字段。
        charge_usd:
          anyOf:
            - type: string
              pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
              description: 精确的美元十进制字符串，小数位数为 2–6，采用唯一规范格式。求和时使用十进制运算或乘以 10^6 转为整数，不使用浮点数。
            - type: 'null'
          description: 此 Solution 响应所含 runs 的总费用，全部 Run 结算前为 null。每个 Run 保留各自费用；失败也可能收费。
        charge_basis:
          anyOf:
            - type: object
              properties:
                clause:
                  type: string
                  enum:
                    - rule
                    - NO_RESULT
                    - PROVIDER_ERROR
                    - TIMED_OUT
                    - INTERNAL
                quantity:
                  anyOf:
                    - type: integer
                      minimum: 0
                    - type: 'null'
              required:
                - clause
                - quantity
              additionalProperties: false
            - type: 'null'
          description: 单个 Run 的计费依据；多个 Run 汇总时为 null。各项费用请查看 runs[].charge_basis。
        stoppable:
          type: boolean
          description: 当前是否可接受停止请求。不保证能在分派前停止 Run。
        stop_requested_at:
          anyOf:
            - type: string
              description: ISO 8601 UTC 时间戳。
              format: date-time
            - type: 'null'
          description: 请求停止的时间。如果已开始分派，Run 仍可能继续。
        created_at:
          type: string
          description: ISO 8601 UTC 时间戳。
          format: date-time
        started_at:
          anyOf:
            - type: string
              description: ISO 8601 UTC 时间戳。
              format: date-time
            - type: 'null'
        completed_at:
          anyOf:
            - type: string
              description: ISO 8601 UTC 时间戳。
              format: date-time
            - type: 'null'
        task_id:
          anyOf:
            - type: string
            - type: 'null'
        metadata:
          type: object
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 500
          maxProperties: 20
          propertyNames:
            type: string
            pattern: ^[a-z][a-z0-9_]{0,39}$
          description: |-
            已保存的追踪字段，可用于筛选 Run，不发送给数据提供商，不影响路由、价格或幂等。

            - 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。
            - 值：长度为 1–500 的字符串。
            - user_id：终端用户的不透明 ID，不得使用邮箱或姓名。
        action:
          type: string
          enum:
            - search
            - list_employees
            - enrich
            - find_email
            - verify_email
            - find_phone
        result_status:
          type: string
          enum:
            - success
            - no_result
            - error
            - pending
          description: >-
            业务交付状态，与 status 中的最终 Run 生命周期独立。no_result 为有效空结果；error
            表示数据提供商输出无法交付。
        error:
          anyOf:
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
              required:
                - code
                - message
              additionalProperties: false
            - type: 'null'
        runs:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              run_url:
                type: string
                description: 在控制台打开 Run，需要工作空间成员权限。
              provider:
                type: string
                pattern: ^[a-z0-9][a-z0-9-]*$
              endpoint:
                type: string
                pattern: ^\/.+$
              endpoint_version:
                type: integer
                exclusiveMinimum: 0
              status:
                type: string
                enum:
                  - QUEUED
                  - RUNNING
                  - COMPLETED
                  - FAILED
                  - STOPPED
                description: >-
                  QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应，包括非 2xx
                  响应。FAILED 请读取 failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。
              failure:
                anyOf:
                  - type: object
                    properties:
                      kind:
                        type: string
                        enum:
                          - TIMED_OUT
                          - INTERNAL
                      message:
                        type: string
                    required:
                      - kind
                      - message
                    additionalProperties: false
                  - type: 'null'
                description: Run 失败原因，仅在 status 为 FAILED 时非 null。
              input:
                type: object
                properties:
                  omitted:
                    type: boolean
                    enum:
                      - true
                required:
                  - omitted
                additionalProperties: false
              output:
                type: object
                properties:
                  omitted:
                    type: boolean
                    enum:
                      - true
                required:
                  - omitted
                additionalProperties: false
              provider_response:
                anyOf:
                  - type: object
                    properties:
                      http_status:
                        type: integer
                        minimum: 100
                        maximum: 599
                        description: 数据提供商返回的 HTTP 状态，即使 Run 为 COMPLETED 也应检查。
                    required:
                      - http_status
                    additionalProperties: false
                  - type: 'null'
              charge_usd:
                anyOf:
                  - type: string
                    pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
                    description: >-
                      精确的美元十进制字符串，小数位数为 2–6，采用唯一规范格式。求和时使用十进制运算或乘以 10^6
                      转为整数，不使用浮点数。
                  - type: 'null'
                description: >-
                  最终费用，精确的美元十进制字符串。QUEUED 或 RUNNING 时为 null。FAILED 状态的 Run
                  仍可能按接口定价产生非零费用。
              charge_basis:
                anyOf:
                  - type: object
                    properties:
                      clause:
                        type: string
                        enum:
                          - rule
                          - NO_RESULT
                          - PROVIDER_ERROR
                          - TIMED_OUT
                          - INTERNAL
                      quantity:
                        anyOf:
                          - type: integer
                            minimum: 0
                          - type: 'null'
                    required:
                      - clause
                      - quantity
                    additionalProperties: false
                  - type: 'null'
                description: 计算费用所用的价格条款。结算前或未尝试调用数据提供商时为 null。
              stoppable:
                type: boolean
                description: 当前是否可接受停止请求。不保证能在分派前停止 Run。
              stop_requested_at:
                anyOf:
                  - type: string
                    description: ISO 8601 UTC 时间戳。
                    format: date-time
                  - type: 'null'
                description: 请求停止的时间。如果已开始分派，Run 仍可能继续。
              created_at:
                type: string
                description: ISO 8601 UTC 时间戳。
                format: date-time
              started_at:
                anyOf:
                  - type: string
                    description: ISO 8601 UTC 时间戳。
                    format: date-time
                  - type: 'null'
              completed_at:
                anyOf:
                  - type: string
                    description: ISO 8601 UTC 时间戳。
                    format: date-time
                  - type: 'null'
              task_id:
                anyOf:
                  - type: string
                  - type: 'null'
              metadata:
                type: object
                additionalProperties:
                  type: string
                  minLength: 1
                  maxLength: 500
                maxProperties: 20
                propertyNames:
                  type: string
                  pattern: ^[a-z][a-z0-9_]{0,39}$
                description: |-
                  已保存的追踪字段，可用于筛选 Run，不发送给数据提供商，不影响路由、价格或幂等。

                  - 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。
                  - 值：长度为 1–500 的字符串。
                  - user_id：终端用户的不透明 ID，不得使用邮箱或姓名。
            required:
              - id
              - run_url
              - provider
              - endpoint
              - endpoint_version
              - status
              - failure
              - input
              - output
              - provider_response
              - charge_usd
              - charge_basis
              - stoppable
              - stop_requested_at
              - created_at
              - started_at
              - completed_at
              - task_id
              - metadata
            additionalProperties: false
        result_url:
          type: string
          description: >-
            通过认证读取规范化结果和总费用的只读 URL 路径，配合 API 服务地址使用。不创建 Run，也不恢复切换。GET
            /v1/runs/:id 仍返回原生单个 Run。
      required:
        - id
        - run_url
        - provider
        - endpoint
        - endpoint_version
        - status
        - failure
        - input
        - output
        - provider_response
        - charge_usd
        - charge_basis
        - stoppable
        - stop_requested_at
        - created_at
        - started_at
        - completed_at
        - task_id
        - metadata
        - action
        - result_status
        - error
        - runs
        - result_url
      additionalProperties: false
    ValidationFailedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    IdempotencyKeyRequiredEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - idempotency_key_required
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    UnauthorizedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    InsufficientBalanceEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - insufficient_balance
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    EndpointNotPermittedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - endpoint_not_permitted
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    ForbiddenEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - forbidden
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    IdempotencyConflictEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - idempotency_conflict
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    RateLimitedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - rate_limited
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    ServiceUnavailableEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - service_unavailable
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
  securitySchemes:
    bearer:
      type: http
      scheme: Bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.