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

> Geben Sie Credits aus, um verifizierte geschäftliche E-Mail-Adresse, private E-Mail-Adresse und Telefonnummer für eine bereits identifizierte Person freizuschalten — Einzel-, Bulk- und Async-Bulk-Muster.

Die Redeem People API wandelt eine `people_search_id` (oder LinkedIn-URL) in den vollständigen Satz verifizierter Kontaktdaten für diese Person um — geschäftliche E-Mail, private E-Mail, Telefon. Sie geben Credits nur aus, wenn tatsächlich Kontaktdaten zurückgegeben werden.

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

## Wann Redeem verwenden

Verwenden Sie Redeem, wenn **Sie bereits wissen, wer die Person ist**, und deren Kontaktdaten benötigen:

* Sie haben [People Search](/de/api-reference/endpoint/people/search) ausgeführt und möchten die Kontaktdaten für die Treffer freischalten
* Sie haben eine LinkedIn-Profil-URL und möchten die Person kontaktieren
* Sie haben eine `people_search_id` aus einer früheren Pubrio-Antwort

Wenn Sie stattdessen eine **E-Mail-Adresse oder Telefonnummer haben und die passende Person finden möchten**, verwenden Sie [People Contact Lookup](/de/developer-guides/people-contact-lookup) — das ist die umgekehrte Richtung und kostet 1 Credit pro Treffer.

## Drei Varianten

| Endpunkt                          | Wann verwenden                | Verhalten                                                                      |
| --------------------------------- | ----------------------------- | ------------------------------------------------------------------------------ |
| `POST /redeem/people`             | Eine Person nach der anderen  | Synchron. Gibt Kontaktdaten in der Antwort zurück.                             |
| `POST /redeem/people/batch`       | 2–N Personen auf einmal       | Asynchron. Gibt sofort eine `redeem_query_id` zurück.                          |
| `POST /redeem/people/batch/query` | Abfrage von Batch-Ergebnissen | Gibt das vollständige Ergebnis-Set zurück, sobald der Batch abgeschlossen ist. |

Der Batch-Ablauf ist das richtige Muster für jeden listengetriebenen Workflow — CSV-Uploads, Aufnahme in Sequenzen, CRM-Synchronisierung — da er die Kontaktauflösung serverseitig parallelisiert.

## Schnellstart — einzelnes 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>

**Antwort:**

```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` gibt Ihr Guthaben nach der Abbuchung sowie die durch diesen Aufruf verbrauchten Credits wieder, sodass Sie einen In-App-Zähler aktualisieren können, ohne einen separaten `/profile/usage`-Aufruf zu machen.

## Identifikatoren

Sie können die einzulösende Person auf zwei Arten identifizieren:

| Identifikator      | Beschreibung                                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `people_search_id` | UUID, die von jedem Pubrio-Such-/Lookup-Endpunkt zurückgegeben wird. Am günstigsten und zuverlässigsten — kein Auflösungsschritt nötig.                                                                                         |
| `linkedin_url`     | Eine LinkedIn-Profil-URL (z. B. `https://www.linkedin.com/in/jane-doe-123`). Pubrio löst diese zunächst zu einer `people_search_id` auf; ist das Profil neu, kann dies einen einmaligen externen Anreicherungsschritt umfassen. |

`people_contact_types` legt fest, was Sie zurückerhalten möchten. Kombinieren Sie beliebig `email-work`, `email-personal`, `phone` — berechnet wird pro zurückgegebenem Typ, nicht pro angefragtem Typ. Fragen Sie `["email-work", "phone"]` an und erhalten nur `email-work` zurück, wird nur die E-Mail berechnet.

## Bulk-Redeem (asynchrones Muster)

Für mehr als eine Person verwenden Sie den Batch-Ablauf. Dieser führt jedes Redeem serverseitig parallel aus und vermeidet die Roundtrip-Kosten pro Anfrage.

**Schritt 1 — einreichen:**

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

**Schritt 2 — abfragen:**

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

Ist `is_completed` gleich `true`, enthält die Antwort das vollständige `peoples`-Array mit aufgelösten Kontaktdaten sowie die gesamten Kreditkosten für den Batch.

<Tip>
  Fragen Sie im von `estimated_time` gemeldeten Rhythmus ab. Ein engmaschigeres Polling als die Schätzung verschwendet nur Roundtrips — die Arbeit ist noch nicht abgeschlossen.
</Tip>

## Kreditkosten

Credits werden **pro zurückgegebenem Kontakt** abgezogen, nicht pro Anfrage. Preise pro Datensatz:

| Kontakttyp                      | Credits pro Datensatz |
| ------------------------------- | --------------------- |
| `email-work` / `email-personal` | 5                     |
| `phone`                         | 10                    |

Hat eine Person keine geschäftliche E-Mail-Adresse und Sie haben nur `email-work` angefragt, wird für diesen Datensatz nichts berechnet. Haben Sie sowohl eine E-Mail-Adresse als auch eine Telefonnummer angefragt und Pubrio liefert beides, werden Sie für beides berechnet. Die vollständige, planabhängige Preistabelle finden Sie unter [Pricing](/de/get-started/pricing).

## Gängige Muster

<CardGroup cols={2}>
  <Card title="Search-→-Redeem-Pipeline" icon="magnifying-glass">
    Führen Sie [People Search](/de/api-reference/endpoint/people/search) aus, lassen Sie den Nutzer Zeilen in Ihrer UI auswählen, und senden Sie die ausgewählten `people_search_id`s dann über `/redeem/people/batch`. Berechnet wird nur das tatsächlich Genutzte.
  </Card>

  <Card title="LinkedIn-URL-Einfüge-Ablauf" icon="linkedin">
    Nehmen Sie eine Liste von LinkedIn-URLs aus einem CRM-Export oder einer Browser-Erweiterung entgegen. Reichen Sie diese über `/redeem/people` (einzeln) ein oder bauen Sie einen kleinen Batch-Wrapper.
  </Card>

  <Card title="Aufnahme in Sequenzen" icon="envelope">
    Lösen Sie vor der Aufnahme von Kontakten in eine Outbound-Sequenz nur `email-work` ein — das hält die Kosten vorhersehbar und versorgt Ihren Sender mit zustellbaren Adressen.
  </Card>

  <Card title="CRM-Anreicherung" icon="database">
    Ordnen Sie bestehende CRM-Datensätze (über [People Lookup](/de/api-reference/endpoint/people/lookup)) einer `people_search_id` zu und lösen Sie diese dann im Batch nach Zeitplan ein.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Werde ich berechnet, wenn kein Kontakt gefunden wird?">
    Nein. Credits werden pro zurückgegebenem Datensatz abgezogen. Hat eine Person keine verfügbare geschäftliche E-Mail-Adresse, zahlen Sie für diesen Kontakt-Slot nichts — selbst wenn Sie ihn angefragt haben.
  </Accordion>

  <Accordion title="Was ist, wenn dieselbe Person zweimal in meinem Batch enthalten ist?">
    Duplikate werden serverseitig entfernt. Sie werden nur einmal berechnet.
  </Accordion>

  <Accordion title="Was passiert, wenn die LinkedIn-URL Pubrio unbekannt ist?">
    Pubrio versucht eine einmalige externe Auflösung. Lässt sich das Profil auflösen, gelten die normalen Redeem-Preise. Andernfalls werden keine Credits berechnet.
  </Accordion>

  <Accordion title="Wie aktuell sind die Kontaktdaten?">
    Pubrio verifiziert E-Mail- und Telefondatensätze fortlaufend erneut. Jeder Kontakt kommt mit einem `status`-Feld (`Verified`, `null` usw.), sodass Sie auf Ihrer Seite nach verifizierten Datensätzen filtern können.
  </Accordion>

  <Accordion title="Kann ich nur Telefon, nur E-Mail oder nur die private E-Mail einlösen?">
    Ja — `people_contact_types` ist ein Array. Übergeben Sie genau die gewünschten Typen; berechnet wird nur, was tatsächlich zurückgegeben wird.
  </Accordion>

  <Accordion title="Bulk vs. Einzeln — wann lohnt sich das asynchrone Muster?">
    Ab etwa 3 Datensätzen gewinnt der Batch bei Latenz und Zuverlässigkeit pro Datensatz. Der Batch-Endpunkt führt intern Fan-out aus und parallelisiert alle externen Anreicherungsschritte, sodass ein 50-Datensatz-Batch näher an 5 Sekunden Wanduhrzeit liegt als an 50 × Roundtrip-Zeit pro Anfrage.
  </Accordion>
</AccordionGroup>

## Siehe auch

<CardGroup cols={2}>
  <Card title="People Contact Lookup" icon="magnifying-glass-arrow-right" href="/de/developer-guides/people-contact-lookup">
    Umgekehrter Lookup: Finden Sie eine Person anhand einer E-Mail-Adresse, Telefonnummer oder eines Namens + Domain. 1 Credit pro Treffer.
  </Card>

  <Card title="People Search" icon="users" href="/de/api-reference/endpoint/people/search">
    Finden Sie Personen, die einem Profil entsprechen (Titel, Standort, Unternehmensgröße, Technologien usw.).
  </Card>

  <Card title="People Lookup" icon="user" href="/de/api-reference/endpoint/people/lookup">
    Lösen Sie das vollständige Profil einer einzelnen Person anhand eines Identifikators auf — ohne Kontaktfreischaltung.
  </Card>

  <Card title="Pricing" icon="coins" href="/de/get-started/pricing">
    Kreditkosten für alle Endpunkte, nach Plan-Stufe.
  </Card>
</CardGroup>