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

> Spend credits to unlock verified work email, personal email, and phone number for a person you have already identified — single, bulk, and async-bulk patterns.

The Redeem People API turns a `people_search_id` (or LinkedIn URL) into the full set of verified contacts — work email, personal email, phone — for that person. You only spend credits when contact data is actually returned.

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

## When to use Redeem

Use Redeem when **you already know who the person is** and you need their contact details:

* You ran [People Search](/en/api-reference/endpoint/people/search) and want to unlock contacts for the matches
* You have a LinkedIn profile URL and want to reach out to the person
* You have a `people_search_id` from a previous Pubrio response

If instead you have an **email or phone and want to find the matching person**, use [People Contact Lookup](/en/developer-guides/people-contact-lookup) — it's the reverse direction and 1 credit per match.

## Three flavors

| Endpoint                          | Use when                  | Behavior                                               |
| --------------------------------- | ------------------------- | ------------------------------------------------------ |
| `POST /redeem/people`             | One person at a time      | Synchronous. Returns contacts in the response.         |
| `POST /redeem/people/batch`       | 2–N people in one shot    | Asynchronous. Returns a `redeem_query_id` immediately. |
| `POST /redeem/people/batch/query` | Polling for batch results | Returns the full result set when the batch completes.  |

The batch flow is the right pattern for any list-driven workflow — CSV uploads, sequence enrollment, CRM sync — because it parallelizes the contact-resolution work server-side.

## Quick start — single 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>

**Response:**

```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` echoes your post-charge balance and the credits this call cost, so you can update an in-app meter without a separate `/profile/usage` round-trip.

## Identifiers

You can identify the person to redeem in two ways:

| Identifier         | Description                                                                                                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `people_search_id` | UUID returned by any Pubrio search/lookup endpoint. Cheapest and most reliable — no resolution step.                                                                                                      |
| `linkedin_url`     | A LinkedIn profile URL (e.g., `https://www.linkedin.com/in/jane-doe-123`). Pubrio resolves it to a `people_search_id` first; if the profile is new, this can include a one-time external enrichment step. |

`people_contact_types` is the contract for what you want back. Mix any of `email-work`, `email-personal`, `phone` — you're charged per type returned, not per type requested. Asking for `["email-work", "phone"]` and getting only `email-work` back charges only for the email.

## Bulk redeem (async pattern)

For more than one person, use the batch flow. It runs each redeem in parallel server-side and avoids the per-request roundtrip cost.

**Step 1 — submit:**

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

**Step 2 — poll:**

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

When `is_completed` is `true`, the response contains the full `peoples` array with resolved contacts and the total credit cost for the batch.

<Tip>
  Poll at the cadence reported by `estimated_time`. Polling tighter than the estimate just wastes round-trips — the work isn't done yet.
</Tip>

## Credit costs

Credits are deducted **per contact returned**, not per request. Pricing per record:

| Contact type                    | Credits per record |
| ------------------------------- | ------------------ |
| `email-work` / `email-personal` | 5                  |
| `phone`                         | 10                 |

If a person has no work email and you only requested `email-work`, you're charged nothing for that record. If you requested both an email and a phone and Pubrio returns both, you're charged for both. See the full [pricing table](/en/get-started/pricing) for plan-specific rates.

## Common patterns

<CardGroup cols={2}>
  <Card title="Search → redeem pipeline" icon="magnifying-glass">
    Run [People Search](/en/api-reference/endpoint/people/search), let the user pick rows in your UI, then send the selected `people_search_id`s through `/redeem/people/batch`. Charge only for what's used.
  </Card>

  <Card title="LinkedIn-URL paste flow" icon="linkedin">
    Accept a list of LinkedIn URLs from a CRM export or browser extension. Submit them via `/redeem/people` (single) or build a small batch wrapper.
  </Card>

  <Card title="Sequence enrollment" icon="envelope">
    Before adding contacts to an outbound cadence, redeem `email-work` only — keeps cost predictable while feeding deliverable addresses to your sender.
  </Card>

  <Card title="CRM enrichment" icon="database">
    Map existing CRM records to `people_search_id` (via [People Lookup](/en/api-reference/endpoint/people/lookup)), then redeem in batch on a schedule.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Will I be charged if no contact is found?">
    No. Credits are deducted per record returned. If a person has no work email available, you pay nothing for that contact slot — even if you asked for it.
  </Accordion>

  <Accordion title="What if the same person is in my batch twice?">
    Duplicates are deduplicated server-side. You're charged once.
  </Accordion>

  <Accordion title="What happens if the LinkedIn URL is unknown to Pubrio?">
    Pubrio attempts a one-time external resolution. If the profile resolves, normal redeem pricing applies. If it doesn't, no credits are charged.
  </Accordion>

  <Accordion title="How fresh is the contact data?">
    Pubrio re-verifies email and phone records on a rolling basis. Each contact comes with a `status` field (`Verified`, `null`, etc.) so you can filter to only verified records on your end.
  </Accordion>

  <Accordion title="Can I redeem only phone, only email, or only personal email?">
    Yes — `people_contact_types` is an array. Pass exactly the types you want; you're only billed on what's returned.
  </Accordion>

  <Accordion title="Bulk vs single — when does the async pattern win?">
    Above \~3 records, batch wins on latency and on per-record reliability. The batch endpoint runs fan-out internally and parallelizes any external enrichment hops, so a 50-record batch is closer to a 5-second wall-clock than 50 × per-request RTT.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="People Contact Lookup" icon="magnifying-glass-arrow-right" href="/en/developer-guides/people-contact-lookup">
    Reverse-lookup: find a person from an email, phone, or name + domain. 1 credit per match.
  </Card>

  <Card title="People Search" icon="users" href="/en/api-reference/endpoint/people/search">
    Find people who match a profile (title, location, company size, technologies, etc.).
  </Card>

  <Card title="People Lookup" icon="user" href="/en/api-reference/endpoint/people/lookup">
    Resolve a single person's full profile from an identifier — no contact unlock.
  </Card>

  <Card title="Pricing" icon="coins" href="/en/get-started/pricing">
    Credit costs across all endpoints, by plan tier.
  </Card>
</CardGroup>