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

# Kontakt-Lookup für Personen

> Ermitteln Sie eine Person anhand von E-Mail, Telefon oder Vor-/Nachname + Unternehmen — ohne people_search_id. 1 Credit pro abrechenbarem Treffer.

Die People Contact Lookup API beantwortet die Frage **„Wem gehört diese E-Mail/Telefonnummer/dieser Name?"** Übergeben Sie einen Identifikator und erhalten Sie eine `people_search_id` sowie das Profil der gefundenen Person zurück — ohne zuvor eine Suche ausführen zu müssen.

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

## Wann Contact Lookup verwenden

Verwenden Sie Contact Lookup, wenn **Sie einen Identifikator haben und die Person dazu finden möchten**:

* Eine E-Mail ist in Ihrem Posteingang gelandet — wer hat sie gesendet, welches Unternehmen, welcher Titel?
* Eine Telefonnummer hat auf Ihrer Vertriebsleitung angerufen — ordnen Sie sie einem bekannten Kontakt zu
* Eine CSV-Liste von Leads mit Namen und Unternehmen, aber ohne Pubrio-IDs — lösen Sie alle in `people_search_id`s auf
* Formularübermittlung mit `email + name` — zu einem vollständigen Kontaktdatensatz anreichern

Wenn Sie stattdessen eine `people_search_id` (oder LinkedIn-URL) haben und die **E-Mail-Adresse + Telefonnummer für diese Person** benötigen, verwenden Sie [People Redeem](/de/developer-guides/people-redeem) — das ist die umgekehrte Richtung.

## Zwei Varianten

| Endpunkt                                   | Wann verwenden                                                                                     |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `POST /redeem/people/contact/lookup`       | Einzel-Lookup — ein Identifikator pro Anfrage.                                                     |
| `POST /redeem/people/contact/lookup/batch` | Batch-Lookup — bis zur Massengrößenbegrenzung Ihres Abonnements pro Anfrage, parallel verarbeitet. |

Beide Endpunkte geben dieselben `match`-Metadaten pro Datensatz zurück (siehe [Match-Metadaten](#match-metadata) unten).

## Schnellstart

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

**Antwort:**

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

## Lookup-Modi

Sie können eine Person auf zwei Arten zuordnen:

### Exakter Treffer — nach E-Mail oder Telefon

Der Standard. Übergeben Sie `email` oder `phone`; Pubrio gleicht anhand des normalisierten Kontaktwerts ab. Dies liefert bei einem Treffer immer `match.confidence: "exact"`.

```json theme={null}
{ "email": "king.lai@pubrio.com" }
```

```json theme={null}
{ "phone": "+15551234567" }
```

### Ähnlichkeitstreffer — nach Name + Domain oder Unternehmen

Wenn Sie keinen eindeutigen Identifikator haben, können Sie auf einen Ähnlichkeitsabgleich zurückgreifen. Übergeben Sie `first_name`, `last_name` sowie entweder `domain` oder `company`, und setzen Sie `is_enable_similarity_search: true`.

```json theme={null}
{
  "first_name": "King",
  "last_name": "Lai",
  "domain": "pubrio.com",
  "is_enable_similarity_search": true
}
```

Pubrio versucht zunächst, einen exakten E-Mail-/Telefon-Treffer zu finden; existiert keiner und ist die Ähnlichkeitssuche aktiviert, werden Kandidaten nach Namensähnlichkeit innerhalb der Unternehmensdomain (oder, falls `domain` fehlt, dem Unternehmensabgleich) eingestuft. Zurückgegebene Treffer tragen `match.confidence: "similarity_domain"` oder `"similarity_company"`, sodass Sie nach Sicherheitsgrad filtern können.

Sie können beides kombinieren: Übergeben Sie eine E-Mail **und** einen Namen + Domain. Der exakte E-Mail-Treffer hat Vorrang; die Namensfelder werden nur zum Fallback, falls die E-Mail nicht aufgelöst werden kann.

## Match-Metadaten

Jeder zurückgegebene Datensatz enthält ein `match`-Objekt, das beschreibt, wie der Treffer zustande kam:

| Feld                       | Werte                | Bedeutung                                                                                                                                                          |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `match.confidence`         | `exact`              | Direkter E-Mail-/Telefon-Treffer. Höchste Sicherheit.                                                                                                              |
|                            | `similarity_domain`  | Namensbasierter Treffer, verankert an einer bekannten Unternehmensdomain.                                                                                          |
|                            | `similarity_company` | Namensbasierter Treffer, verankert an einem Unternehmensnamen (keine Domain).                                                                                      |
| `match.input`              | `{ value, type }`    | Gibt den Identifikator wieder, der zum Treffer geführt hat, sodass Sie in Ihrer UI „gefunden über `king.lai@pubrio.com`" anzeigen können.                          |
| `match.is_duplicate_input` | boolean              | `true`, wenn derselbe Identifikator zuvor bereits in einem Batch aufgetaucht ist — der Lookup wird nur einmal durchgeführt, und das Duplikat wird nicht berechnet. |

Verwenden Sie `match.confidence`, um nachgelagerte Aktionen zu steuern: z. B. nur `exact`-Treffer automatisch in eine Sequenz aufnehmen; `similarity_*`-Treffer zur manuellen Prüfung weiterleiten.

## Batch-Lookup

Reichen Sie in einer Anfrage bis zur Massengrößenbegrenzung Ihres Abonnements ein. Jeder Eintrag verwendet dieselben Identifikatoren wie der Einzel-Lookup-Body.

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

Der Batch ist synchron — die Antwort enthält alle aufgelösten Datensätze in derselben Reihenfolge wie die Eingabe. Nicht zugeordnete Eingaben werden aus der Antwort entfernt (sie erscheinen gar nicht und werden nicht berechnet).

## Kreditkosten

**1 Credit pro abrechenbarem Treffer.** Konkret:

* Ein erfolgreicher Treffer (exakt oder Ähnlichkeit) → 1 Credit
* Kein Treffer → 0 Credits
* Doppelte Eingabe innerhalb eines Batches → 0 Credits (einmal aufgelöst, einmal berechnet)

Damit ist Contact Lookup um eine Größenordnung günstiger als [Redeem](/de/developer-guides/people-redeem) — Sie zahlen dafür, eine Person zu **identifizieren**, nicht dafür, ihre Kontaktdaten **freizuschalten**. Wenn Sie nach dem Lookup auch die E-Mail-Adresse/Telefonnummer benötigen, lösen Sie die zurückgegebene `people_search_id` ein.

## Gängige Muster

<CardGroup cols={2}>
  <Card title="Anreicherung eingehender E-Mails" icon="envelope-open">
    Suchen Sie bei jeder eingehenden E-Mail den Absender nach. Zeigen Sie dessen Unternehmen, Titel und `people_search_id` in Ihrer CRM- oder Helpdesk-Ansicht an.
  </Card>

  <Card title="CSV-zu-CRM-Auflösung" icon="file-csv">
    Lösen Sie eine CSV-Liste von `name + company`-Zeilen zu kanonischen `people_search_id`s auf. Zeilen ohne exakten Treffer erhalten automatisch einen Ähnlichkeitsversuch.
  </Card>

  <Card title="Anreicherung von Formularübermittlungen" icon="form">
    Übergeben Sie `{ email }` aus Ihrem Marketingformular. Erhalten Sie Unternehmen, Titel und eine Pubrio-ID zurück, die Sie durch Scoring-Regeln leiten können.
  </Card>

  <Card title="Lookup-→-Redeem-Pipeline" icon="arrow-right-arrow-left">
    Zweistufiger Ablauf: günstiger Lookup (1 Credit), um die Person zu identifizieren, dann vollständiges Redeem (5–10 Credits) nur für Treffer oberhalb eines Sicherheits-Schwellenwerts.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Gibt Contact Lookup verifizierte E-Mail-Adresse und Telefonnummer zurück?">
    Nein — Contact Lookup gibt das Profil der Person zurück (`people_search_id`, Name, Unternehmen, Domain, Titel usw.) plus Match-Metadaten. Um die verifizierten Kontaktdaten selbst zu erhalten, übergeben Sie die zurückgegebene `people_search_id` an [Redeem](/de/developer-guides/people-redeem).
  </Accordion>

  <Accordion title="Was ist der Unterschied zwischen similarity_domain und similarity_company?">
    `similarity_domain` bedeutet, dass wir den Namensabgleich an einer bekannten Unternehmensdomain verankert haben — die stärkste der Ähnlichkeitsstufen. `similarity_company` bedeutet, dass wir an einem Unternehmensnamen ohne kanonische Domain verankert haben — etwas weniger zuverlässig, da mehrere nicht verwandte Unternehmen denselben Namen tragen können.
  </Accordion>

  <Accordion title="Werde ich für nicht zugeordnete Eingaben berechnet?">
    Nein. Nicht zugeordnete Eingaben werden stillschweigend aus der Antwort entfernt und nicht in Rechnung gestellt.
  </Accordion>

  <Accordion title="Was passiert, wenn ich dieselbe E-Mail-Adresse zweimal in einem Batch sende?">
    Das Duplikat wird serverseitig erkannt, der Lookup wird einmal ausgeführt, und es wird einmal berechnet. Der doppelte Eintrag wird in der Antwort mit `match.is_duplicate_input: true` markiert.
  </Accordion>

  <Accordion title="Wie hoch ist die Batch-Größenbegrenzung?">
    Die Obergrenze wird in Ihrem Abonnement als `people_contact_enrichment_bulk_size` festgelegt. Die meisten Pläne erlauben 100+ pro Aufruf; kontaktieren Sie uns, wenn Sie eine höhere Obergrenze benötigen.
  </Accordion>

  <Accordion title="Kann ich nach LinkedIn-URL suchen?">
    Nicht bei Contact Lookup. Verwenden Sie [Redeem](/de/developer-guides/people-redeem) mit `linkedin_url`, wenn Sie ein LinkedIn-Profil haben und sowohl die Auflösung als auch die Kontaktdaten in einem Aufruf möchten.
  </Accordion>

  <Accordion title="Was passiert bei internationalen Telefonnummern?">
    Telefonnummern werden anhand einer normalisierten Form abgeglichen. International (E.164) ist die zuverlässigste Eingabeform. Nummern im nationalen Format können übereinstimmen, wenn sich das Land ableiten lässt, aber E.164 (`+15551234567`) vermeidet Mehrdeutigkeiten.
  </Accordion>
</AccordionGroup>

## Siehe auch

<CardGroup cols={2}>
  <Card title="People Redeem" icon="key" href="/de/developer-guides/people-redeem">
    Vorwärtsrichtung: Credits ausgeben, um E-Mail-Adresse + Telefonnummer für eine bekannte `people_search_id` oder LinkedIn-URL freizuschalten.
  </Card>

  <Card title="People Search" icon="users" href="/de/api-reference/endpoint/people/search">
    Finden Sie Personen, die einem Job-/Unternehmens-/Standortfilter entsprechen.
  </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 bekannten Identifikators auf.
  </Card>

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