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

# 人员联系方式查询

> 通过邮箱、电话或姓名 + 公司反向查找人员——无需 people_search_id。每次可计费匹配仅 1 个积分。

People Contact Lookup API 用来回答\*\*"这个邮箱/电话/姓名属于谁？"\*\* 把标识传给它，立即得到 `people_search_id` 和匹配人员的资料——无需先跑一轮搜索。

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/contact/lookup \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "king.lai@pubrio.com" }'
```

## 何时使用 Contact Lookup

当**您手中有标识、需要找出对应人员**时使用 Contact Lookup：

* 收件箱里出现的邮件——发件人是谁、属于哪家公司、什么职位？
* 销售线响起的电话号码——匹配到已知联系人
* 一份只有姓名 + 公司、没有 Pubrio ID 的潜客 CSV——一次性解析为 `people_search_id`
* 含 `email + name` 的表单提交——补全为完整联系人记录

如果反过来您持有 `people_search_id`（或 LinkedIn URL），希望**取得该人员的邮箱 + 电话**，请改用 [人员兑换](/cn/developer-guides/people-redeem)——这是正向流程。

## 两种调用形式

| 端点                                         | 适用场景                       |
| ------------------------------------------ | -------------------------- |
| `POST /redeem/people/contact/lookup`       | 单次查询——每次请求一个标识。            |
| `POST /redeem/people/contact/lookup/batch` | 批量查询——单次请求最多至订阅的批量上限，并行处理。 |

两个端点对每条记录返回相同的 `match` 元数据（参见下文 [匹配元数据](#match-metadata)）。

## 快速开始

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.pubrio.com/redeem/people/contact/lookup \
    -H "pubrio-api-key: $PUBRIO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "email": "king.lai@pubrio.com" }'
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.pubrio.com/redeem/people/contact/lookup", {
    method: "POST",
    headers: {
      "pubrio-api-key": process.env.PUBRIO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email: "king.lai@pubrio.com" }),
  });
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://api.pubrio.com/redeem/people/contact/lookup",
      headers={"pubrio-api-key": os.environ["PUBRIO_API_KEY"]},
      json={"email": "king.lai@pubrio.com"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**响应：**

```json theme={null}
{
  "data": {
    "profile": {
      "credit": 450375,
      "topup_credit": 235236,
      "total_credit_cost": 1
    },
    "peoples": [
      {
        "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
        "first_name": "King",
        "last_name": "Lai",
        "people_name": "King Lai",
        "company_name": "Pubrio",
        "domain": "pubrio.com",
        "match": {
          "confidence": "exact",
          "input": { "value": "king.lai@pubrio.com", "type": "email-work" },
          "is_duplicate_input": false
        }
      }
    ]
  }
}
```

## 匹配模式

匹配人员有两种方式：

### 精确匹配——通过邮箱或电话

默认行为。传入 `email` 或 `phone`；Pubrio 会在归一化后的联系方式值上做匹配。命中时 `match.confidence` 始终为 `"exact"`。

```json theme={null}
{ "email": "king.lai@pubrio.com" }
```

```json theme={null}
{ "phone": "+15551234567" }
```

### 相似度匹配——通过姓名 + 域名或公司

若您没有确定性标识，可以退而使用相似度匹配。传入 `first_name`、`last_name`，加上 `domain` 或 `company` 之一，并设置 `is_enable_similarity_search: true`。

```json theme={null}
{
  "first_name": "King",
  "last_name": "Lai",
  "domain": "pubrio.com",
  "is_enable_similarity_search": true
}
```

Pubrio 会先尝试精确的邮箱/电话命中；若没有命中且相似度搜索已启用，则在公司域名（或在未传 `domain` 时按公司名）下按姓名相近度对候选进行排序。命中的记录会带有 `match.confidence: "similarity_domain"` 或 `"similarity_company"`，便于您按确定性筛选。

二者可以组合：同时传入邮箱**和**姓名 + 域名。精确邮箱匹配优先；姓名字段仅在邮箱无法解析时作为兜底。

## 匹配元数据

每条返回的记录都包含一个 `match` 对象，描述该匹配是如何产生的：

| 字段                         | 取值                   | 含义                                                     |
| -------------------------- | -------------------- | ------------------------------------------------------ |
| `match.confidence`         | `exact`              | 直接的邮箱/电话匹配。最高确定性。                                      |
|                            | `similarity_domain`  | 锚定在已知公司域名上的姓名相似度匹配。                                    |
|                            | `similarity_company` | 锚定在公司名（无域名）上的姓名相似度匹配。                                  |
| `match.input`              | `{ value, type }`    | 回显本次产生命中的输入标识，便于您在 UI 中显示如"匹配于 `king.lai@pubrio.com`"。 |
| `match.is_duplicate_input` | boolean              | 当同一个标识在批次中重复出现时为 `true`——查询只执行一次，重复条目不计费。              |

可以根据 `match.confidence` 控制下游动作：例如仅将 `exact` 自动入组到序列；将 `similarity_*` 路由到人工复核。

## 批量查询

单次请求最多可提交至您订阅计划的批量上限。每个条目接受与单次查询请求体相同的标识符。

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/contact/lookup/batch \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "peoples": [
      { "email": "king.lai@pubrio.com" },
      { "first_name": "John", "last_name": "Smith", "domain": "example.com" }
    ],
    "is_enable_similarity_search": true
  }'
```

批量查询为同步调用——响应按输入顺序包含全部已解析的记录。未匹配的输入会从响应中被丢弃（不出现也不计费）。

## 积分消耗

**每次可计费匹配 1 个积分。** 具体来说：

* 成功匹配（精确或相似度）→ 1 积分
* 无匹配 → 0 积分
* 批次中的重复输入 → 0 积分（仅解析一次，仅扣费一次）

因此 Contact Lookup 比 [Redeem](/cn/developer-guides/people-redeem) 便宜一个数量级——您支付的是**识别**人员的代价，而非**解锁**联系方式的代价。如果识别后还需要邮箱/电话，再用返回的 `people_search_id` 去 redeem 即可。

## 常见用法

<CardGroup cols={2}>
  <Card title="入站邮件丰富" icon="envelope-open">
    每收到一封邮件就查询发件人。在 CRM 或工单视图中显示其公司、职位与 `people_search_id`。
  </Card>

  <Card title="CSV → CRM 解析" icon="file-csv">
    将一份 `姓名 + 公司` 的 CSV 解析为标准的 `people_search_id`。无法精确匹配的会自动尝试相似度。
  </Card>

  <Card title="表单提交丰富" icon="form">
    用您营销表单中的 `{ email }` 调用，获得公司、职位以及可用于评分规则的 Pubrio ID。
  </Card>

  <Card title="查询 → 兑换 流水线" icon="arrow-right-arrow-left">
    两步流程：先用低成本查询（1 积分）识别人员，再仅对超过置信阈值的匹配执行完整 redeem（5–10 积分）。
  </Card>
</CardGroup>

## 常见问题

<AccordionGroup>
  <Accordion title="Contact Lookup 会返回经过验证的邮箱与电话吗？">
    不会——Contact Lookup 只返回人员资料（`people_search_id`、姓名、公司、域名、职位等）以及匹配元数据。要拿到经过验证的联系方式本身，请将返回的 `people_search_id` 传给 [Redeem](/cn/developer-guides/people-redeem)。
  </Accordion>

  <Accordion title="similarity_domain 与 similarity_company 有何区别？">
    `similarity_domain` 表示姓名匹配锚定在已知公司域名上——是相似度层级中最可靠的。`similarity_company` 表示锚定在公司名上但无标准域名——略弱一些，因为同名公司之间可能并不相关。
  </Accordion>

  <Accordion title="未匹配的输入会被扣费吗？">
    不会。未匹配的输入会被静默从响应中丢弃，且不计费。
  </Accordion>

  <Accordion title="同一封邮件在一个批次中传两次会怎样？">
    服务器端会侦测到重复，仅执行一次查询并扣一次费。重复条目会在响应中被标记为 `match.is_duplicate_input: true`。
  </Accordion>

  <Accordion title="批量大小上限是多少？">
    上限由订阅设置中的 `people_contact_enrichment_bulk_size` 决定。多数计划支持单次 100+；如需更高上限请联系我们。
  </Accordion>

  <Accordion title="可以通过 LinkedIn URL 查询吗？">
    Contact Lookup 不支持。如果您持有 LinkedIn 资料并希望一次完成解析与联系方式获取，请使用 [Redeem](/cn/developer-guides/people-redeem) 配合 `linkedin_url`。
  </Accordion>

  <Accordion title="国际电话号码如何处理？">
    电话以归一化形式匹配。国际格式（E.164）最为可靠。可推断国家时本地格式也可能命中，但 E.164（`+15551234567`）能避免歧义。
  </Accordion>
</AccordionGroup>

## 相关页面

<CardGroup cols={2}>
  <Card title="人员兑换（Redeem）" icon="key" href="/cn/developer-guides/people-redeem">
    正向流程：消耗积分以解锁已知 `people_search_id` 或 LinkedIn URL 的邮箱与电话。
  </Card>

  <Card title="People Search" icon="users" href="/cn/api-reference/endpoint/people/search">
    按职位/公司/地点等过滤条件查找人员。
  </Card>

  <Card title="People Lookup" icon="user" href="/cn/api-reference/endpoint/people/lookup">
    通过已知标识获取某人完整资料。
  </Card>

  <Card title="价格" icon="coins" href="/cn/get-started/pricing">
    各端点的积分消耗按计划层级一览。
  </Card>
</CardGroup>