> ## 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](/ko/api-reference/endpoint/people/search) 를 실행한 뒤 매칭 결과의 연락처를 잠금 해제하고 싶을 때
* LinkedIn 프로필 URL 이 있어 해당 인물에게 연락하고 싶을 때
* 이전 Pubrio 응답에서 받은 `people_search_id` 를 가지고 있을 때

반대로 **이메일이나 전화번호로 해당 인물을 찾고 싶다면** [인물 연락처 조회](/ko/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` 를 별도로 호출하지 않고 앱 내 사용량 미터를 갱신할 수 있습니다.

## 식별자

Redeem 대상 인물은 두 가지 방식으로 식별할 수 있습니다:

| 식별자                | 설명                                                                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 을 병렬 실행해 요청별 왕복 비용을 피합니다.

**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 가 둘 다 반환한다면 둘 다 청구됩니다. 플랜별 상세 단가는 [요금](/ko/get-started/pricing) 페이지를 참고하세요.

## 일반적인 패턴

<CardGroup cols={2}>
  <Card title="검색 → Redeem 파이프라인" icon="magnifying-glass">
    [People Search](/ko/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` 만 redeem — 비용을 예측 가능하게 유지하면서 발신측에 도달 가능한 주소를 공급할 수 있습니다.
  </Card>

  <Card title="CRM 보강" icon="database">
    [People Lookup](/ko/api-reference/endpoint/people/lookup) 으로 기존 CRM 레코드를 `people_search_id` 에 매핑한 뒤, 정해진 일정에 일괄 redeem 합니다.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="연락처를 찾지 못해도 청구되나요?">
    아니요. 크레딧은 반환된 레코드당 차감됩니다. 인물에게 업무 이메일이 없다면, 해당 슬롯을 요청했더라도 비용이 발생하지 않습니다.
  </Accordion>

  <Accordion title="같은 사람이 일괄 처리에 두 번 들어가면?">
    중복은 서버에서 자동 제거됩니다. 청구는 한 번만 됩니다.
  </Accordion>

  <Accordion title="LinkedIn URL 이 Pubrio 에 알려지지 않은 경우는?">
    Pubrio 는 일회성 외부 해석을 시도합니다. 프로필이 해석되면 일반 redeem 단가가 적용되며, 해석되지 않으면 크레딧이 차감되지 않습니다.
  </Accordion>

  <Accordion title="연락처 데이터는 얼마나 신선한가요?">
    Pubrio 는 이메일과 전화 레코드를 롤링 방식으로 재검증합니다. 각 연락처에 `status` 필드(`Verified`, `null` 등)가 함께 제공되어 검증된 항목만 필터링할 수 있습니다.
  </Accordion>

  <Accordion title="전화만, 이메일만, 또는 개인 이메일만 redeem 할 수 있나요?">
    네 — `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="/ko/developer-guides/people-contact-lookup">
    역방향 조회: 이메일, 전화번호, 또는 이름 + 도메인으로 인물 찾기. 매칭당 1 크레딧.
  </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>