> ## 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 マッチにつき 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 を使う場面

**識別子を持っていて、対応する人物を見つけたい**ときに使用します：

* 受信箱に届いたメール — 送信者は誰、どの会社、肩書は何？
* 営業ラインに鳴った電話番号 — 既知の連絡先と突き合わせる
* 名前 + 会社名のみで Pubrio ID のないリードの CSV — 一気に `people_search_id` に解決
* `email + name` を含むフォーム送信 — 完全な連絡先レコードへエンリッチ

逆に、`people_search_id`（または LinkedIn URL）から**その人物のメール + 電話を取りたい**場合は、[人物リディーム](/jp/developer-guides/people-redeem)を使ってください — 順方向の処理です。

## 2 つの呼び出し形式

| エンドポイント                                    | 用途                                 |
| ------------------------------------------ | ---------------------------------- |
| `POST /redeem/people/contact/lookup`       | 単一ルックアップ — リクエストごとに識別子 1 件。        |
| `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
        }
      }
    ]
  }
}
```

## マッチモード

人物のマッチ方法は 2 通りです：

### 完全一致 — メールまたは電話で

デフォルト動作です。`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` — ルックアップは 1 回のみ実行され、重複分は課金されません。          |

`match.confidence` で下流の動作を制御できます。例えば、`exact` のみシーケンスへ自動登録し、`similarity_*` は手動レビューに回す、など。

## 一括ルックアップ

サブスクリプションのバルク上限まで 1 リクエストで送信できます。各エントリは単一ルックアップのリクエストボディと同じ識別子を受け付けます。

```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 クレジット。** 具体的には：

* マッチ成功（完全一致または類似度）→ 1 クレジット
* マッチなし → 0 クレジット
* バッチ内の重複入力 → 0 クレジット（解決は 1 回、課金は 1 回）

このため Contact Lookup は [Redeem](/jp/developer-guides/people-redeem) よりも 1 桁安いコストで使えます — 払っているのは人物の**特定**であって、連絡先の**アンロック**ではありません。ルックアップ後にメール／電話も必要になったら、返ってきた `people_search_id` をリディームすれば OK です。

## よくあるパターン

<CardGroup cols={2}>
  <Card title="受信メールのエンリッチメント" icon="envelope-open">
    すべての受信メールで送信者をルックアップ。会社名、肩書、`people_search_id` を CRM やヘルプデスクのビューに表示。
  </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">
    2 段階フロー：低コストルックアップ（1 クレジット）で人物を特定し、確信度しきい値以上のマッチに対してのみフルリディーム（5〜10 クレジット）。
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Contact Lookup は検証済みのメールと電話を返しますか？">
    いいえ — Contact Lookup が返すのは人物プロフィール（`people_search_id`、名前、会社、ドメイン、肩書 など）とマッチメタデータです。検証済みの連絡先そのものを取得するには、返却された `people_search_id` を [Redeem](/jp/developer-guides/people-redeem) に渡してください。
  </Accordion>

  <Accordion title="similarity_domain と similarity_company の違いは？">
    `similarity_domain` は名前マッチを既知の企業ドメインに紐付けたもの — 類似度ティアの中で最も信頼性が高いです。`similarity_company` は標準ドメインのない会社名にアンカーしたもの — 同名の無関係な会社が複数存在し得るため、若干信頼性は劣ります。
  </Accordion>

  <Accordion title="マッチしなかった入力に課金されますか？">
    いいえ。マッチしなかった入力はレスポンスから静かに除外され、課金もされません。
  </Accordion>

  <Accordion title="同じメールをバッチで 2 回送るとどうなりますか？">
    重複はサーバ側で検出され、ルックアップは 1 回だけ実行され、課金も 1 回のみです。重複エントリはレスポンスで `match.is_duplicate_input: true` とフラグが付きます。
  </Accordion>

  <Accordion title="バッチサイズの上限は？">
    上限はサブスクリプション設定の `people_contact_enrichment_bulk_size` で決まります。多くのプランは 1 コール 100+ を許可。さらに高い上限が必要な場合はお問い合わせください。
  </Accordion>

  <Accordion title="LinkedIn URL でルックアップできますか？">
    Contact Lookup ではできません。LinkedIn プロフィールがあり、解決と連絡先取得を 1 コールで完結させたい場合は、`linkedin_url` を伴って [Redeem](/jp/developer-guides/people-redeem) を使用してください。
  </Accordion>

  <Accordion title="国際電話番号はどう扱われますか？">
    電話は正規化形式で照合されます。国際表記（E.164）が最も信頼できる入力です。国を推定できる場合は国内表記でも一致しますが、E.164（`+15551234567`）であれば曖昧さが排除されます。
  </Accordion>
</AccordionGroup>

## 関連ページ

<CardGroup cols={2}>
  <Card title="人物リディーム" icon="key" href="/jp/developer-guides/people-redeem">
    順方向：既知の `people_search_id` または LinkedIn URL の人物について、クレジット消費でメール + 電話をアンロック。
  </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>