Entscheider finden (discover_people)
discover_people ist der zweite Schritt nach Firmen entdecken: Du übergibst Zielfirmen (als Domains oder als Liste) und beschreibst die Persona, HiWalter liefert die passenden Personen gruppiert nach Firma.
Ohne Firmenvorgabe sucht der Endpunkt im gesamten Index, z. B. “alle Vertriebsleiter bei SaaS-Firmen in Bayern”.
Standardmäßig bekommst du nur Kontakte mit verifizierter E-Mail (Risiko-Score A oder B). Mehr zu den Scores unter Risiko-Scores.
Nutze diesen Endpunkt, um:
- zu einer Firmenliste die 1-3 richtigen Entscheider pro Firma zu ziehen
- Personen zu finden, die neu im Job sind (stärkstes Kaufsignal)
- Buying Committees aufzubauen (z. B. Geschäftsführung + Vertriebsleitung)
Fair-Use-Richtlinie: Dieser Endpunkt unterliegt unserer Fair-Use-Richtlinie für die Suche.
POST https://api.hiwalter.de/api/v1/tools/discover_peopleAuthentifizierung
Section titled “Authentifizierung”Übergib deinen API-Schlüssel als Bearer-Token im Authorization-Header. Schlüssel folgen dem Format hw_XXXXXXXXXXX.
Anfrage
Section titled “Anfrage”Der Body wird als application/json gesendet. Alle Felder sind optional.
| Parameter | Typ | Beschreibung |
|---|---|---|
domains | string[] | Zielfirmen als Domains, bis zu 10.000. |
list_id | string | Alternativ: Zielfirmen aus einer gespeicherten Liste. |
persona_text | string | Beschreibung der Persona in normaler Sprache, z. B. “die Person, die über Vertriebstools entscheidet”. Wird semantisch gegen Titel, Headline und Profil gematcht. |
persona_prompt | string | Ein Satz, aus dem HiWalter Seniorität, Abteilung und Titel-Keywords selbst ableitet. Die Werte stehen in applied_filters. |
seniority | enumstring[] | Senioritätsstufen wie bei der Personensuche: Owner, C Suite, Partner, VP, Head, Director, Manager, Senior, Entry. |
department | enumstring[] | Abteilungen wie bei der Personensuche, z. B. Sales, Marketing, Operations. |
title | string[] | Titel-Begriffe. Phrasen in Anführungszeichen werden wörtlich gematcht, + markiert Pflichtbegriffe. Abkürzungen werden erweitert: "CEO" findet auch “Geschäftsführer”. |
negate_title | string[] | Titel ausschließen, z. B. ["Assistenz", "Werkstudent", "Praktikant"]. |
person_country | string[] | Land der Person (nicht der Firma), z. B. ["Germany"] oder ["DACH"]. |
new_in_role_since | string | Nur Personen, die ihre aktuelle Position nach diesem Datum angetreten haben (YYYY-MM-DD). Neue Entscheider bauen ihren Stack neu auf. |
per_company | integer | Maximale Anzahl Kontakte pro Firma (Standard: 3, max.: 50). |
email_risk | enumstring[] | Erlaubte Risiko-Scores der E-Mail. Standard: ["A", "B"]. Mit ["A", "B", "C", "D", "F"] bekommst du auch unsichere Adressen. |
require | enumstring[] | Pflichtfelder pro Kontakt. Optionen: email, linkedin, phone. Standard: ["email"]. |
exclude_list_id | string | Personen oder Firmen einer gespeicherten Liste ausschließen, z. B. bereits kontaktierte Leads. |
limit | integer | Maximale Anzahl Firmen pro Seite (Standard: 100, max.: 1.000). |
cursor | string | Cursor aus next_cursor der vorherigen Antwort. |
save_as_list | string | Speichert das Ergebnis als Kontaktliste unter diesem Namen. |
Beispiel
Section titled “Beispiel”curl --request POST \ --url https://api.hiwalter.de/api/v1/tools/discover_people \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "list_id": "lst_maschinenbau_nrw", "persona_text": "die Person, die über Vertrieb und Neukundengewinnung entscheidet", "seniority": [ "Owner", "C Suite", "Head" ], "negate_title": [ "Assistenz", "Werkstudent" ], "per_company": 2, "email_risk": [ "A", "B" ]}'Antwort
Section titled “Antwort”{ "results": { "companies": [ { "domain": "mueller-maschinenbau.de", "name": "Müller Maschinenbau GmbH", "employees": "51-200", "email_pattern": "{first_initial}.{last}@mueller-maschinenbau.de", "contacts": [ { "full_name": "Anna Becker", "first_name": "Anna", "last_name": "Becker", "title": "Geschäftsführerin", "seniority": "C Suite", "department": "Operations", "linkedin_url": "https://linkedin.com/in/anna-becker-123", "business_email": "a.becker@mueller-maschinenbau.de", "business_email_risk_score": "A", "job_start_date": "2026-08-01", "country": "Germany", "city": "Bielefeld", "similarity": 88, "_id": "anna-becker-123" } ] } ], "total_companies": 1312, "total_contacts": 2207, "next_cursor": "eyJvIjoxMDB9" }, "applied_filters": { "seniority": [ "Owner", "C Suite", "Head" ] }, "status": "ok", "metadata": { "fair_use": { "records_remaining_5h": 179999, "records_reset_5h": "2026-11-02T18:53:16Z", "records_remaining_1w": 899999, "records_reset_1w": "2026-11-09T13:53:16Z" } }}| Feld | Typ | Beschreibung |
|---|---|---|
results.companies | array | Firmen mit mindestens einem passenden Kontakt. |
results.companies[].domain | string | Domain der Firma. |
results.companies[].email_pattern | string | Erkanntes E-Mail-Muster der Firma, nützlich für E-Mail finden. |
results.companies[].contacts | array | Passende Personen, sortiert nach similarity. |
results.companies[].contacts[].title | string | Aktuelle Position. |
results.companies[].contacts[].seniority | string | Senioritätsstufe. |
results.companies[].contacts[].business_email | string | Verifizierte geschäftliche E-Mail. |
results.companies[].contacts[].business_email_risk_score | string | Risiko-Score der E-Mail (A-F). |
results.companies[].contacts[].job_start_date | string | Seit wann die Person in der aktuellen Position ist. |
results.companies[].contacts[].similarity | integer | Passung zur Persona (0-100), nur bei persona_text oder persona_prompt. |
results.total_companies | integer | Firmen mit passenden Kontakten insgesamt. |
results.total_contacts | integer | Passende Kontakte insgesamt. |
results.next_cursor | string | Cursor für die nächste Seite. |
applied_filters | object | Tatsächlich angewendete Filter. |
metadata.fair_use | object | Verbleibendes Kontingent. |
- Mit
per_company: 1und einer engensenioritybekommst du eine saubere 1-Kontakt-pro-Firma-Liste für Cold Email. new_in_role_sinceauf die letzten 90 Tage setzen: neue Geschäftsführer und Vertriebsleiter sind die offensten Empfänger.- Zähle vorher kostenlos mit Entscheider zählen.