# Contact (https://webmetic.de/docs/api/datenmodell/contact)

Wenn zum Beispiel jemand von Bergquell Mineralbrunnen mehrmals Ihre Preisseite liest, finden Sie mit `/contacts/search` dort die Leitung Marketing. Ansprechpartner stammen aus der Kontaktsuche, nicht aus dem Tracking.

## Regeln [#regeln]

Für jeden Contact gelten diese Regeln:

- **Nur besuchende Unternehmen**: Die `company_id` muss zu einem Unternehmen gehören, das eine Ihrer Websites besucht hat. Sonst antworten `search`, `lookup` und `find` mit `COMPANY_NOT_IDENTIFIED`. Die API sucht nicht nach Domain, Name oder Person.
- **Einrichtung zuerst**: Sie richten die Ansprechpartner einmal im Dashboard für Ihr Konto ein. Bis dahin antworten `search`, `reveal` und `find` mit `CONTACTS_SETUP_REQUIRED`. Wie das geht, steht unter [Ansprechpartner einrichten](https://webmetic.de/docs/ansprechpartner/einrichten).
- **Credits**: Suche und Lookup kosten keine Credits. `reveal` und `find` kosten Credits, aber nur für die Daten, die Webmetic liefert. Mehr dazu unter [Credits in der API](https://webmetic.de/docs/api/credits).
- **Ein Konto, ein Bestand**: Freigeschaltete Daten gehören Ihrem Konto. Alle Benutzer, das Dashboard, die API und der KI-Assistent sehen sie ohne neue Kosten. Ein anderes Webmetic-Konto sieht sie nicht.
- **Free-Plan**: Für Unternehmen, die im Free-Plan verborgen sind, antworten `search`, `lookup` und `find` mit `PLAN_REQUIRED`. Mehr dazu unter [Pläne](https://webmetic.de/docs/konto/plaene).
- **Zugang**: Wenn Ihr Partner die Funktion **Datenprofile** abgeschaltet hat, antwortet die API mit `FEATURE_DISABLED`.

Alle Fehlercodes stehen unter [Fehler](https://webmetic.de/docs/api/fehler).

## Felder [#felder]

So liefern `/contacts/search` und `/contacts/lookup` eine Ansprechperson in der Liste `contacts`:

| Feld | Typ | Beispiel | Beschreibung |
| --- | --- | --- | --- |
| `contact_id` | `string` | `"v1.q7Rk2mXv9TnL4w"` | Feste Kennung der Person, die Sie an `/contacts/reveal` geben. Nie `null`. Behandeln Sie die Kennung als Text ohne festes Format |
| `name` | `string` oder `null` | `"Miriam Eckhardt"` | Vor- und Nachname |
| `job_title` | `string` oder `null` | `"Leiterin Marketing"` | Position im Unternehmen |
| `company_name` | `string` oder `null` | `"Bergquell Mineralbrunnen GmbH"` | Arbeitgeber laut Kontaktdaten. Kann vom `company_name` der [Company](https://webmetic.de/docs/api/datenmodell/company) abweichen |
| `has_email` | `boolean` | `true` | Eine E-Mail-Adresse liegt vor |
| `has_phone` | `boolean` | `true` | Eine Rufnummer liegt vor |
| `has_social_link` | `boolean` | `true` | Ein LinkedIn-Profil liegt vor |
| `email` | `string` oder `null` | `"m.eckhardt@bergquell.example"` | E-Mail-Adresse, nach dem Freischalten der E-Mail |
| `linkedin` | `string` oder `null` | `"https://www.linkedin.com/in/miriam-eckhardt-example"` | URL des LinkedIn-Profils, nach dem Freischalten der E-Mail |
| `direct_phone` | `string` oder `null` | `null` | Durchwahl oder geschäftliche Rufnummer, nach dem Freischalten des Telefons |
| `mobile_phone` | `string` oder `null` | `null` | Mobilnummer, nach dem Freischalten des Telefons |

Der Contact enthält Abteilung, Ebene und Standort der Person nicht, auch wenn Sie nach Abteilung oder Ebene filtern.

## Felder bis zum Freischalten [#felder-bis-zum-freischalten]

Vier Felder bleiben leer, bis Ihr Konto die Daten freischaltet:

- **E-Mail**: Das Freischalten füllt `email` und `linkedin`.
- **Telefon**: Das Freischalten füllt `direct_phone` und `mobile_phone`.

Die Suche liefert diese vier Felder immer als `null`, auch für Personen, die Ihr Konto schon freigeschaltet hat. `/contacts/lookup` liefert freigeschaltete Daten mit und lässt leere Felder ganz weg. Wenn Ihr Konto dieses Unternehmen mit diesen Filtern noch nicht gesucht hat, antwortet der Lookup genau mit `{"exists": false}`.

## Contact in reveal und find [#contact-in-reveal-und-find]

Nach dem Freischalten hat der Contact eine andere Form:

| Endpunkt | Form | Felder der Person |
| --- | --- | --- |
| `/contacts/reveal` | Objekt `contact` | `contact_id`, `email`, `linkedin`, `direct_phone`, `mobile_phone`. Was Ihr Konto nicht freigeschaltet hat, ist `null` |
| `/contacts/find` | Flach in der Antwort, mit `found` | `contact_id`, `name`, `job_title`, `company_name`, `email`, `linkedin`, `direct_phone`, `mobile_phone`. Bei `found: false` sind alle `null` |

`search`, `reveal` und `find` melden dazu `credits_used`, die Credits dieses Aufrufs, und `credits_remaining`, die Credits Ihres Kontos danach.

## Land der Treffer [#land-der-treffer]

Webmetic sucht Personen im Land des Unternehmens. `country` nennt dieses Land als ISO-Code mit zwei Großbuchstaben, zum Beispiel `DE`.

Wenn die Suche dort niemanden findet, sucht Webmetic weltweit und setzt `country_fallback` auf `true`. Wenn kein Land bekannt ist, ist `country` `null`, und die Suche läuft ebenfalls weltweit.

Beide Felder stehen in der Antwort von `search`, `lookup` und `find`, nicht im einzelnen Contact. Der Lookup lässt `country` weg, wenn es `null` ist.

## Seiten [#seiten]

Die Seiten von `/contacts/search` beginnen bei 0. Eine Seite enthält 10 bis 25 Personen, standardmäßig 25. `total` zählt alle passenden Personen, nicht nur die dieser Seite. Im Lookup heißt das Feld `total_results`, und der Lookup liefert nur die erste Seite. Mehr dazu unter [Paginierung](https://webmetic.de/docs/api/paginierung).

## Beispiel [#beispiel]

Das Beispiel zeigt eine Suche bei Bergquell Mineralbrunnen vor dem Freischalten:

```json title="POST /contacts/search"
{
  "total": 14,
  "page": 0,
  "contacts": [
    {
      "contact_id": "v1.q7Rk2mXv9TnL4w",
      "name": "Miriam Eckhardt",
      "job_title": "Leiterin Marketing",
      "company_name": "Bergquell Mineralbrunnen GmbH",
      "has_email": true,
      "has_phone": true,
      "has_social_link": true,
      "email": null,
      "linkedin": null,
      "direct_phone": null,
      "mobile_phone": null
    }
  ],
  "from_cache": false,
  "country": "DE",
  "country_fallback": false
}
```

Die Antwort ist gekürzt: `credits_used` und `credits_remaining` fehlen. `from_cache: true` heißt, das Ergebnis stammt aus einer gespeicherten Suche.

## Sonderfälle [#sonderfälle]

- **`404` beim Freischalten**: Wenn die Person nicht aus einer Suche Ihres Kontos stammt oder nicht mehr auffindbar ist, antwortet `/contacts/reveal` mit `CONTACT_NOT_FOUND`. Suchen Sie erneut und nutzen Sie die `contact_id` aus dem neuen Ergebnis.
- **Keine Herausgabe**: Für manche Personen darf Webmetic keine Kontaktdaten herausgeben. Dann antwortet die API mit `404` und bucht keine Credits ab.
- **Erneut freischalten**: `/contacts/reveal` liefert Daten, die Ihr Konto schon freigeschaltet hat, erneut und ohne Kosten.
- **Leer trotz `has_email`**: Wenn Webmetic beim Freischalten keine Adresse findet, bleibt `email` `null`. Diese Datenart kostet dann nichts und bleibt offen.
- **Unternehmen ohne Website**: Wenn zum Unternehmen keine Website hinterlegt ist, antworten `search`, `lookup` und `find` mit `404` und `COMPANY_WITHOUT_WEBSITE`. Für dieses Unternehmen liefert die API keine Ansprechpartner.
- **Kein Treffer bei find**: Wenn niemand passt, antwortet `/contacts/find` mit `found: false` und bucht nichts ab.

## Verwendet von [#verwendet-von]

- **Endpunkte**: [`POST /contacts/search`](https://webmetic.de/docs/api/referenz/contacts/search) zum Suchen, [`GET /contacts/lookup`](https://webmetic.de/docs/api/referenz/contacts/lookup) für gespeicherte Suchen mit freigeschalteten Daten, [`POST /contacts/reveal`](https://webmetic.de/docs/api/referenz/contacts/reveal) zum Freischalten und [`POST /contacts/find`](https://webmetic.de/docs/api/referenz/contacts/find) zum Finden und Freischalten in einem Aufruf
- **KI-Assistent**: Auch der [KI-Assistent](https://webmetic.de/docs/ki-assistent/tools-und-prompts) sucht Ansprechpartner und schaltet sie frei, mit den Tools `find_contacts` und `reveal_contact`.