---
name: hiwalter-discovery
description: Baut aus einer ICP-Beschreibung eine Zielliste deutscher Firmen und Entscheider über die HiWalter-API. Nutze diesen Skill, wenn jemand deutsche B2B-Firmen oder Entscheider finden, eine Leadliste aufbauen, den adressierbaren Markt kostenlos abschätzen oder Firmennamen zu Domains auflösen will.
---

# HiWalter Discovery

Findet deutsche Firmen und die richtigen Entscheider dazu. Der Ablauf ist immer: erst kostenlos zählen, dann gezielt ziehen. So weißt du, wie groß dein Markt ist, bevor Kontingent verbraucht wird.

## Voraussetzungen

- API-Key im Format `hw_XXXXXXXXXXX` (HiWalter-App, `app.hiwalter.de`). Free-Plan reicht zum Testen (1.000 Calls).
- Basis-URL: `https://api.hiwalter.de/api/v1/tools/`
- Jede Anfrage: Header `Authorization: Bearer hw_...` und `Content-Type: application/json`, Body als JSON.
- Geografie: Standard ist Deutschland (`country: ["Germany"]`). Österreich und die Schweiz oder der Alias `["DACH"]` sind möglich, aber nur setzen, wenn ausdrücklich gewünscht.

## Ablauf

### 1. Markt zählen (kostenlos, immer zuerst)

`count_companies` nimmt dieselben Filter wie `discover_companies`, liefert aber nur die Anzahl und kostet nichts. Verfeinere die Filter so lange, bis die Menge sinnvoll ist.

```
POST /count_companies
{ "icp_text": "Steuerberatungskanzleien mit Schwerpunkt digitale Buchhaltung",
  "country": ["Germany"], "employee_range": "11,200" }
```

Analog `count_people` für Kontakte, ebenfalls kostenlos.

### 2. Firmen entdecken

`discover_companies` beschreibt den Markt statt starrer Filter. Drei kombinierbare Wege:

- `seed_domains` (bis 10): Lookalikes deiner besten Kunden.
- `icp_text`: ICP in normaler Sprache (was die Firma tut, nicht welche Filter gelten).
- `phrase_match` (bis 20): exakte Begriffe, die auf der Website stehen müssen.

Nützliche Filter: `state` (Bundesland), `near` (Umkreis), `industry` / `sub_industry`, `employee_range`, `revenue_range`, `founded_after` (Neugründungen), `legal_form` (z. B. `"GmbH"`), `tech_stack` (Anbieter-Domain), `exclude_domains` / `exclude_list_id` (Bestandskunden aussteuern). Steuere Breite über `relevance` (`MAX_RELEVANCE` / `BALANCED` / `MAX_COVERAGE`). Seiten über `limit` (max. 1.000) und `cursor` (`next_cursor`). Mit `save_as_list` als Liste speichern.

### 3. Entscheider finden

`discover_people` nimmt Zielfirmen (`domains` bis 10.000 oder `list_id`) und eine Persona und liefert Kontakte gruppiert nach Firma.

- Persona: `persona_text` (normale Sprache) oder strukturiert `seniority` / `department` / `title` (+ `negate_title`).
- `per_company` (Standard 3), `new_in_role_since` (neue Entscheider = starkes Kaufsignal).
- Reachability: `require` (Standard `["email"]`) und `email_risk` (Standard `["A","B"]`, also nur verifizierte Adressen). Für mehr Reichweite bei mehr Risiko `["A","B","C","D","F"]`.

```
POST /discover_people
{ "list_id": "lst_maschinenbau_nrw",
  "persona_text": "die Person, die über Vertrieb und Neukundengewinnung entscheidet",
  "seniority": ["Owner","C Suite","Head"], "per_company": 2,
  "require": ["email"], "email_risk": ["A","B"] }
```

### 4. Firmennamen zu Domains

Wenn eine Liste nur Namen hat (Messekatalog, Verband, alter CRM-Export): `match_companies` mit `companies` (bis 100 synchron, größer asynchron über `get_task`). Jeder Treffer hat `match_confidence`; bei Namensgleichheit `city` und `country` mitgeben. Danach weiter mit `discover_people` oder Enrichment.

## Regeln

- Immer erst `count_*` (kostenlos), dann ziehen. Das spart Kontingent und zeigt die Marktgröße.
- Standard-Geografie Deutschland; DACH nur auf ausdrücklichen Wunsch.
- Kontakte standardmäßig nur mit verifizierter E-Mail (A/B). Niedrigere Scores nur bewusst zulassen.
- Keine Telefonnummern anfragen oder versprechen; HiWalter liefert verifizierte E-Mails mit A-bis-F-Score.
- Ergebnisse mit `save_as_list` benennen, damit Enrichment und Verification darauf aufsetzen können.
