# Ansprechpartner finden und freischalten in einem Schritt (Credits) (https://webmetic.de/docs/api/referenz/contacts/find)

## POST /contacts/find

Für Automationen (n8n, Make, Zapier), wo niemand aus einer Liste auswählt:
sucht wie /contacts/search, nimmt den ersten Treffer, bei dem die
gewünschten Daten vorliegen (sonst den ersten mit einem Teil davon), und
schaltet sie frei wie /contacts/reveal. Abgerechnet wird nur, was
tatsächlich geliefert wird; bereits freigeschaltete Daten kosten nichts.
Dieselbe Anfrage wählt wieder dieselbe Person, Wiederholungen sind also
kostenlos. Passt niemand: `found: false`, nichts berechnet.

### 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 |
| `reveal` | "email" \| "phone" \| "both" | nein | email = E-Mail und LinkedIn, phone = Rufnummern, both = beides. Die Kosten je Aktion in Credits liefert GET /contacts/credits |

### Antworten

| Status | Beschreibung |
| --- | --- |
| 200 | Der ausgewählte Kontakt mit den freigeschalteten Daten, oder found=false ohne Kosten, wenn niemand passt |
| 402 | INSUFFICIENT_CREDITS: die Credits des Kontos reichen nicht, nichts wurde berechnet oder 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, oder CONTACT_NOT_FOUND: der Kontakt ist nicht mehr abrufbar |
| 409 | CONCURRENT_UPDATE: dieselbe Freischaltung läuft bereits oder eine andere Credit-Buchung lief gleichzeitig, bitte erneut versuchen |
| 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 |
| --- | --- | --- | --- |
| `found` | boolean | ja | false: niemand passt zu den Filtern oder hat die gewünschten Daten; dann wurde nichts freigeschaltet und nichts berechnet |
| `contact_id` | string \| null | nein | Kennung des ausgewählten Kontakts |
| `name` | string \| null | nein | Vor- und Nachname |
| `job_title` | string \| null | nein | Position im Unternehmen |
| `company_name` | string \| null | nein | Unternehmen des Kontakts |
| `email` | string \| null | nein | E-Mail-Adresse; null, wenn nicht angefragt oder nicht vorhanden |
| `linkedin` | string \| null | nein | LinkedIn-Profil; null, wenn nicht angefragt oder nicht vorhanden |
| `direct_phone` | string \| null | nein | Durchwahl; null, wenn nicht angefragt oder nicht vorhanden |
| `mobile_phone` | string \| null | nein | Mobilnummer; null, wenn nicht angefragt oder nicht vorhanden |
| `total` | integer | ja | Treffer der Suche, aus denen ausgewählt wurde |
| `country` | string \| null | nein | ISO-Ländercode des Unternehmenssitzes, auf den die Suche eingegrenzt war; null = weltweit |
| `country_fallback` | boolean | nein | true: in diesem Land gab es keine Treffer, ausgewählt wurde aus Treffern weltweit |
| `credits_used` | integer | ja | Credits, die dieser Aufruf verbraucht hat |
| `credits_remaining` | integer | ja | Credits des Kontos nach dem Aufruf |

### Beispiel

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