# Ansprechpartner bei einem identifizierten Unternehmen suchen (https://webmetic.de/docs/api/referenz/contacts/search)

## POST /contacts/search

Sucht Ansprechpartner bei einem Unternehmen, das Ihre Website besucht hat
(company_id aus /company-sessions oder /company). Die Suche ist kostenlos;
Credits kosten erst E-Mail und Rufnummern über /contacts/reveal oder
/contacts/find. Filter aus dem Body, sonst aus der ICP-Konfiguration des
Kontos. Jede Seite (max. 25 Treffer) ist eine eigene Suche. Die Treffer sind auf
das Sitzland des Unternehmens eingegrenzt (`country`, aus den
Besucherdaten); gibt es dort niemanden, wird weltweit gesucht und
`country_fallback` gesetzt.

### Anfrage

`application/json`

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `company_id` | string | ja | company_id eines Unternehmens, das Ihre Website besucht hat (aus /company-sessions oder /company) |
| `filters` | SearchFilters \| null | nein | Ohne Angabe gilt die ICP-Konfiguration des Kontos |
| `filters.departments` | string[] \| null | nein | Abteilungen, z. B. Marketing, Sales, Engineering |
| `filters.seniority` | integer[] \| null | nein | Seniorität: 10=Gründer, 9=C-Level, 8=VP, 7=Partner, 6=Director, 5=Manager, 4=Senior, 3=Einsteiger (Standard: 4-10) |
| `filters.require_email` | boolean \| null | nein | Nur Kontakte mit verfügbarer E-Mail |
| `filters.require_phone` | boolean \| null | nein | Nur Kontakte mit verfügbarer Rufnummer |
| `page` | integer | nein | Seite (0-basiert) |
| `size` | integer | nein | Treffer pro Seite (10 bis 25) |

### Antworten

| Status | Beschreibung |
| --- | --- |
| 200 | Treffer mit Verfügbarkeits-Flags; E-Mail und Rufnummer werden erst über /contacts/reveal freigeschaltet |
| 403 | API-Key fehlt, ist ungültig oder unbekannt, FEATURE_DISABLED (Datenprofile ist für Ihr Konto ausgeschaltet), CONTACTS_SETUP_REQUIRED (Ansprechpartner-Einrichtung im Dashboard noch nicht abgeschlossen), COMPANY_NOT_IDENTIFIED (das Unternehmen hat Ihre Website nicht besucht) oder PLAN_REQUIRED (im Free-Plan verborgenes Unternehmen) |
| 404 | COMPANY_WITHOUT_WEBSITE: keine Website zum Unternehmen bekannt |
| 422 | VALIDATION_ERROR: der Body fehlt oder ist ungültig; `errors` nennt jedes Problem |
| 500 | INTERNAL_ERROR: unerwarteter Serverfehler |
| 502 | PROVIDER_UNAVAILABLE oder PROVIDER_ERROR: Datenquelle vorübergehend nicht erreichbar |

Felder der Antwort 200:

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `request_id` | string \| null | nein | Veraltet, nur zur Information |
| `total` | integer | ja | Treffer insgesamt |
| `page` | integer | ja | Diese Seite, 0-basiert |
| `contacts` | ContactBasic[] | ja | Treffer dieser Seite |
| `contacts[].contact_id` | string | ja | Opake, dauerhafte Kennung (z. B. v1.abc) |
| `contacts[].name` | string \| null | nein | Vor- und Nachname |
| `contacts[].job_title` | string \| null | nein | Position im Unternehmen |
| `contacts[].company_name` | string \| null | nein | Unternehmen des Kontakts |
| `contacts[].has_email` | boolean | nein | true: eine E-Mail-Adresse liegt vor und kann freigeschaltet werden |
| `contacts[].has_phone` | boolean | nein | true: eine Rufnummer liegt vor und kann freigeschaltet werden |
| `contacts[].has_social_link` | boolean | nein | true: ein LinkedIn-Profil liegt vor |
| `contacts[].email` | string \| null | nein | E-Mail-Adresse; null, bis sie freigeschaltet ist |
| `contacts[].linkedin` | string \| null | nein | LinkedIn-Profil; null, bis es mit der E-Mail freigeschaltet ist |
| `contacts[].direct_phone` | string \| null | nein | Durchwahl; null, bis die Rufnummern freigeschaltet sind |
| `contacts[].mobile_phone` | string \| null | nein | Mobilnummer; null, bis die Rufnummern freigeschaltet sind |
| `from_cache` | boolean | nein | true: das Ergebnis lag schon vor und wurde nicht neu abgefragt |
| `credits_used` | integer | ja | Credits, die dieser Aufruf verbraucht hat |
| `credits_remaining` | integer | ja | Credits des Kontos nach dem Aufruf |
| `country` | string \| null | nein | ISO-Ländercode des Unternehmenssitzes, auf den die Treffer eingegrenzt sind; null = weltweit |
| `country_fallback` | boolean | nein | true: in diesem Land gab es keine Treffer, gezeigt werden Treffer weltweit |

### Beispiel

```bash
curl -X POST 'https://hub.webmetic.de/contacts/search' \
  -H 'Authorization: wmtc_IHR_API_SCHLUESSEL' \
  -H 'Content-Type: application/json' \
  -d '{"company_id":"41ea486a9c95"}'
```