> ## 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 사용 시점

**식별자를 가지고 있고 그에 해당하는 인물을 찾고 싶을 때** 사용하세요:

* 받은 편지함의 메일 — 보낸 사람은 누구이며, 어느 회사, 어떤 직책인가?
* 영업 라인에 울린 전화번호 — 알려진 연락처와 매칭
* 이름 + 회사명만 있고 Pubrio ID 가 없는 리드 CSV — 한 번에 `people_search_id` 로 해석
* `email + name` 이 포함된 폼 제출 — 완전한 연락처 레코드로 보강

반대로 `people_search_id`(또는 LinkedIn URL)를 가지고 있어 **그 인물의 이메일 + 전화번호를 얻고 싶다면** [인물 교환(Redeem)](/ko/developer-guides/people-redeem) 을 사용하세요 — 정방향 처리입니다.

## 두 가지 호출 방식

| 엔드포인트                                      | 사용 상황                                |
| ------------------------------------------ | ------------------------------------ |
| `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
        }
      }
    ]
  }
}
```

## 매칭 모드

인물을 매칭하는 방법은 두 가지입니다:

### 정확 매칭 — 이메일 또는 전화로

기본 동작입니다. `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](/ko/developer-guides/people-redeem) 보다 한 자릿수 더 저렴합니다 — 비용을 지불하는 대상은 인물의 **식별**이지 연락처의 **잠금 해제**가 아닙니다. 조회 후 이메일/전화도 필요해지면, 반환된 `people_search_id` 로 redeem 하면 됩니다.

## 일반적인 패턴

<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="조회 → Redeem 파이프라인" icon="arrow-right-arrow-left">
    2단계 흐름: 저렴한 조회(1 크레딧)로 인물을 식별한 뒤, 확신도 임계값을 넘는 매칭에 대해서만 전체 redeem(5–10 크레딧).
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Contact Lookup 이 검증된 이메일과 전화를 반환하나요?">
    아니요 — Contact Lookup 은 인물 프로필(`people_search_id`, 이름, 회사, 도메인, 직책 등)과 매칭 메타데이터를 반환합니다. 검증된 연락처 자체를 받으려면 반환된 `people_search_id` 를 [Redeem](/ko/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 프로필이 있고 해석과 연락처 획득을 한 번에 처리하고 싶다면 `linkedin_url` 과 함께 [Redeem](/ko/developer-guides/people-redeem) 을 사용하세요.
  </Accordion>

  <Accordion title="국제 전화번호는 어떻게 처리되나요?">
    전화는 정규화된 형식으로 매칭됩니다. 국제 형식(E.164)이 가장 안정적입니다. 국가를 추정할 수 있으면 국내 형식도 매칭될 수 있지만, E.164(`+15551234567`)가 모호함을 제거합니다.
  </Accordion>
</AccordionGroup>

## 관련 페이지

<CardGroup cols={2}>
  <Card title="인물 교환(Redeem)" icon="key" href="/ko/developer-guides/people-redeem">
    정방향: 알려진 `people_search_id` 또는 LinkedIn URL 의 인물에 대해 크레딧을 사용해 이메일 + 전화 잠금 해제.
  </Card>

  <Card title="People Search" icon="users" href="/ko/api-reference/endpoint/people/search">
    직무/회사/지역 등의 필터로 인물 검색.
  </Card>

  <Card title="People Lookup" icon="user" href="/ko/api-reference/endpoint/people/lookup">
    알려진 식별자로 단일 인물의 전체 프로필 조회.
  </Card>

  <Card title="요금" icon="coins" href="/ko/get-started/pricing">
    모든 엔드포인트의 크레딧 비용을 플랜별로 한눈에.
  </Card>
</CardGroup>