> ## 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.

# 人员兑换（Redeem）

> 消耗积分以解锁已识别人员的工作邮箱、个人邮箱与电话号码——支持单条、批量与异步批量等模式。

Redeem People API 将一个 `people_search_id`（或 LinkedIn URL）转换为该人员的完整经验证联系方式集合——工作邮箱、个人邮箱、电话。仅在实际返回联系方式数据时才会消耗积分。

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
    "people_contact_types": ["email-work", "phone"]
  }'
```

## 何时使用 Redeem

当**您已经知道这个人是谁**并需要其联系方式时，使用 Redeem：

* 您运行了 [People Search](/cn/api-reference/endpoint/people/search) 并希望解锁匹配人员的联系方式
* 您已有 LinkedIn 个人主页 URL 并希望与该人员取得联系
* 您持有来自先前 Pubrio 响应的 `people_search_id`

如果您手中是**邮箱或电话，希望反向查找匹配的人员**，请改用 [人员联系方式查询](/cn/developer-guides/people-contact-lookup)——方向相反，每次匹配仅消耗 1 个积分。

## 三种调用形式

| 端点                                | 适用场景       | 行为                         |
| --------------------------------- | ---------- | -------------------------- |
| `POST /redeem/people`             | 一次处理一人     | 同步。在响应中返回联系方式。             |
| `POST /redeem/people/batch`       | 一次提交 2 至多人 | 异步。立即返回 `redeem_query_id`。 |
| `POST /redeem/people/batch/query` | 轮询批量结果     | 批量任务完成后返回完整结果集。            |

任何由名单驱动的工作流（CSV 上传、序列入组、CRM 同步等）都建议使用批量流程——服务器端可并行处理联系方式解析。

## 快速开始 — 单条 Redeem

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.pubrio.com/redeem/people \
    -H "pubrio-api-key: $PUBRIO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
      "people_contact_types": ["email-work", "phone"]
    }'
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.pubrio.com/redeem/people", {
    method: "POST",
    headers: {
      "pubrio-api-key": process.env.PUBRIO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      people_search_id: "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
      people_contact_types: ["email-work", "phone"],
    }),
  });
  const { data } = await res.json();
  ```

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

  res = requests.post(
      "https://api.pubrio.com/redeem/people",
      headers={"pubrio-api-key": os.environ["PUBRIO_API_KEY"]},
      json={
          "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
          "people_contact_types": ["email-work", "phone"],
      },
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**响应：**

```json theme={null}
{
  "data": {
    "profile": {
      "credit": 450376,
      "topup_credit": 235237,
      "total_credit_cost": 15
    },
    "peoples": [
      {
        "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
        "emails": [
          { "value": "king.lai@pubrio.com", "type": "email-work", "status": "Verified" }
        ],
        "phones": [
          { "value": "+15551234567", "type": "phone", "status": null }
        ]
      }
    ]
  }
}
```

`profile` 会回传扣费后的余额和本次调用消耗的积分，您可以据此更新应用内的额度仪表，无需再额外请求一次 `/profile/usage`。

## 标识方式

可通过两种方式来确定要兑换的人员：

| 标识                 | 说明                                                                                                                           |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `people_search_id` | 由任意 Pubrio 搜索/查找端点返回的 UUID。最经济、最可靠——无需解析步骤。                                                                                  |
| `linkedin_url`     | LinkedIn 个人主页 URL（如 `https://www.linkedin.com/in/jane-doe-123`）。Pubrio 会先将其解析为 `people_search_id`；若该资料为新档案，可能包含一次性的外部数据增强步骤。 |

`people_contact_types` 用于声明您希望返回的内容。可任意组合 `email-work`、`email-personal`、`phone`——按实际返回的类型扣费，而非按申请的类型。请求 `["email-work", "phone"]` 但只返回了 `email-work`，则只对该邮箱扣费。

## 批量 Redeem（异步模式）

需要处理多人时，请使用批量流程。它在服务器端并行执行每条 redeem，避免逐请求往返开销。

**第一步——提交：**

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/batch \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "peoples": [
      "540574d1-ff74-475b-aea2-f8ae643b806d",
      "e37ccf38-ea8f-422e-9874-cb23b15e8fe4"
    ],
    "people_contact_types": ["email-work", "phone"]
  }'
```

```json theme={null}
{
  "data": {
    "redeem_query_id": "a046c1da-b3d4-4ca1-aca6-1dd8c8055701",
    "is_completed": false,
    "estimated_time": 6,
    "estimated_time_type": "second"
  }
}
```

**第二步——轮询：**

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/batch/query \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redeem_query_id": "a046c1da-b3d4-4ca1-aca6-1dd8c8055701" }'
```

当 `is_completed` 为 `true` 时，响应会包含完整的 `peoples` 数组、已解析的联系方式以及本批次的总积分消耗。

<Tip>
  按 `estimated_time` 提示的间隔进行轮询。比预估时间更频繁的轮询只是浪费往返——任务还没完成。
</Tip>

## 积分消耗

按**实际返回的联系方式条数**扣费，而非按请求次数。每条记录的费率：

| 联系方式类型                          | 每条记录消耗的积分 |
| ------------------------------- | --------- |
| `email-work` / `email-personal` | 5         |
| `phone`                         | 10        |

若某人无工作邮箱且您只请求了 `email-work`，则该记录不会扣费。若您同时请求邮箱与电话且 Pubrio 两者都返回，则两者都会扣费。各计划的具体费率请参考完整的[价格表](/cn/get-started/pricing)。

## 常见用法

<CardGroup cols={2}>
  <Card title="搜索 → 兑换 流水线" icon="magnifying-glass">
    运行 [People Search](/cn/api-reference/endpoint/people/search)，让用户在 UI 中勾选条目，然后将所选的 `people_search_id` 通过 `/redeem/people/batch` 提交。仅按实际使用扣费。
  </Card>

  <Card title="粘贴 LinkedIn URL 流程" icon="linkedin">
    接受来自 CRM 导出或浏览器扩展的一组 LinkedIn URL。通过 `/redeem/people`（单条）提交，或自行包装一层批量逻辑。
  </Card>

  <Card title="序列入组" icon="envelope">
    在将联系人加入外呼节奏之前，仅兑换 `email-work`——既能控制成本，又能向发送端提供可送达的地址。
  </Card>

  <Card title="CRM 数据增强" icon="database">
    通过 [People Lookup](/cn/api-reference/endpoint/people/lookup) 将既有 CRM 记录映射为 `people_search_id`，然后按计划批量兑换。
  </Card>
</CardGroup>

## 常见问题

<AccordionGroup>
  <Accordion title="如果没有找到联系方式，是否会扣费？">
    不会。积分按返回的记录扣费。若某人没有可用的工作邮箱，即使您请求过，也不会因该联系方式槽位扣费。
  </Accordion>

  <Accordion title="同一个人在我的批次中出现两次怎么办？">
    服务器会自动去重，仅扣费一次。
  </Accordion>

  <Accordion title="如果 Pubrio 不认识该 LinkedIn URL 会怎样？">
    Pubrio 会尝试一次性外部解析。若解析成功，按常规 redeem 规则计费；若解析失败，则不扣任何积分。
  </Accordion>

  <Accordion title="联系方式数据有多新？">
    Pubrio 滚动复核邮箱与电话记录。每条联系方式都附带 `status` 字段（如 `Verified`、`null` 等），便于您在自己的端筛选仅经过验证的记录。
  </Accordion>

  <Accordion title="可以只兑换电话、只兑换邮箱、或只兑换个人邮箱吗？">
    可以——`people_contact_types` 是数组。仅传入您需要的类型；只对实际返回的内容扣费。
  </Accordion>

  <Accordion title="批量 vs 单条——异步模式何时更优？">
    超过约 3 条记录时，批量在延迟与单条可靠性上都更优。批量端点会在内部进行扇出并行化任何外部增强调用，因此 50 条的批量更接近 5 秒的实际墙钟时间，而非 50 × 单请求 RTT。
  </Accordion>
</AccordionGroup>

## 相关页面

<CardGroup cols={2}>
  <Card title="人员联系方式查询" icon="magnifying-glass-arrow-right" href="/cn/developer-guides/people-contact-lookup">
    反向查找：通过邮箱、电话或姓名 + 域名找到对应人员。每次匹配 1 个积分。
  </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>