> ## 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 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](/jp/api-reference/endpoint/people/search) を実行し、該当者の連絡先をアンロックしたい
* LinkedIn のプロフィール URL があり、その人物にコンタクトしたい
* 過去の Pubrio レスポンスから取得した `people_search_id` がある

逆に**メールや電話があり、それに該当する人物を見つけたい**場合は、[人物連絡先ルックアップ](/jp/developer-guides/people-contact-lookup)を使用してください — 反対方向の処理で、1 マッチあたり 1 クレジットです。

## 3 つの呼び出し形式

| エンドポイント                           | 用途         | 動作                             |
| --------------------------------- | ---------- | ------------------------------ |
| `POST /redeem/people`             | 1 件ずつ処理    | 同期。レスポンスで連絡先を返却。               |
| `POST /redeem/people/batch`       | 2〜N 件をまとめて | 非同期。即座に `redeem_query_id` を返却。 |
| `POST /redeem/people/batch/query` | 一括結果のポーリング | バッチ完了時に結果一式を返却。                |

リスト駆動のワークフロー（CSV アップロード、シーケンス登録、CRM 同期など）には一括フローが最適です — サーバ側で連絡先解決を並列化できるためです。

## クイックスタート — 単一リディーム

<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` を別途呼び出さずにアプリ内のメーターを更新できます。

## 識別子

リディーム対象の人物は 2 通りの方法で識別できます：

| 識別子                | 説明                                                                                                                                                   |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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` のみが返ってきた場合、課金はそのメールのみです。

## 一括リディーム（非同期パターン）

複数人を扱う場合は一括フローを使用します。サーバ側で各リディームを並列実行し、リクエストごとの往復コストを回避します。

**ステップ 1 — 投入：**

```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"
  }
}
```

**ステップ 2 — ポーリング：**

```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 が両方を返却した場合は両方が課金対象になります。プラン別の詳細料金は[料金一覧](/jp/get-started/pricing)を参照してください。

## よくあるパターン

<CardGroup cols={2}>
  <Card title="検索 → リディーム パイプライン" icon="magnifying-glass">
    [People Search](/jp/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">
    既存 CRM レコードを [People Lookup](/jp/api-reference/endpoint/people/lookup) 経由で `people_search_id` にマッピングし、定期的に一括リディーム。
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="連絡先が見つからなかった場合も課金されますか？">
    いいえ。クレジットは返却されたレコードに対してのみ減算されます。仕事用メールが利用できない人物の場合、その連絡先枠を要求していたとしても課金されません。
  </Accordion>

  <Accordion title="同じ人物がバッチに 2 回含まれていたら？">
    重複はサーバ側でデデュープされます。課金は 1 回のみです。
  </Accordion>

  <Accordion title="LinkedIn URL が Pubrio に未登録だった場合は？">
    Pubrio は一回限りの外部解決を試みます。プロフィールが解決できれば通常のリディーム料金が適用され、解決できなければクレジットは消費されません。
  </Accordion>

  <Accordion title="連絡先データはどれくらい新しいですか？">
    Pubrio はメールと電話レコードをローリングで再検証しています。各連絡先には `status` フィールド（`Verified`、`null` など）が付くため、検証済みのレコードのみで絞り込めます。
  </Accordion>

  <Accordion title="電話のみ、メールのみ、個人メールのみのリディームはできますか？">
    可能です — `people_contact_types` は配列です。必要な種別のみを渡してください。課金は実際に返却された分にのみ発生します。
  </Accordion>

  <Accordion title="一括 vs 単一 — 非同期パターンが有利になるのはいつから？">
    およそ 3 件以上で、一括は遅延と件数あたりの信頼性の両方で有利になります。一括エンドポイントは内部でファンアウトし、外部エンリッチメントの呼び出しも並列化するため、50 件のバッチは 50 × 単件 RTT ではなく、5 秒程度のウォールクロックに近づきます。
  </Accordion>
</AccordionGroup>

## 関連ページ

<CardGroup cols={2}>
  <Card title="人物連絡先ルックアップ" icon="magnifying-glass-arrow-right" href="/jp/developer-guides/people-contact-lookup">
    逆引き：メール、電話、または姓名 + ドメインから人物を探します。1 マッチあたり 1 クレジット。
  </Card>

  <Card title="People Search" icon="users" href="/jp/api-reference/endpoint/people/search">
    役職、地域、企業規模、テクノロジーなどの条件で人物を検索。
  </Card>

  <Card title="People Lookup" icon="user" href="/jp/api-reference/endpoint/people/lookup">
    識別子から単一人物の完全プロフィールを取得 — 連絡先のアンロックは行いません。
  </Card>

  <Card title="料金" icon="coins" href="/jp/get-started/pricing">
    全エンドポイントのクレジット消費をプランごとに一覧表示。
  </Card>
</CardGroup>