Nach Personen suchen

So baust du präzise Personensuchen mit Hi Walter: den richtigen Filter wählen, nicht auf dünn gefüllten Feldern über-filtern und paginieren, ohne Records zu verbrennen.

search_people ist die breiteste Fläche der API: sechzehn Parameter, die meisten davon Exact-Match. Der Unterschied zwischen einer guten und einer verschwendeten Suche liegt fast immer darin, zu welchem Filter du greifst, nicht wie viele du stapelst.

Starte mit einem kostenlosen Count

search_linkedin_profile akzeptiert count_only: true. Das gibt die Anzahl der passenden Treffer zurück, ohne Daten abzurufen oder Tokens zu berechnen. Nutze es, um eine Suche vorab zu dimensionieren, bevor du dich festlegst.

{ "name": "John Smith", "company_domain": "acme.com", "count_only": true }

Tokens werden nur berechnet, wenn Daten gefunden und zurückgegeben werden. Eine Suche, die nichts findet, kostet nichts, zählt aber trotzdem gegen dein Rate-Limit. Siehe Rate Limits.

Teste mit limit: 1, bevor du eine Seite ziehst

count_only gibt es nur bei search_linkedin_profile. Bei search_people gibt es keinen kostenlosen Trockenlauf. Der günstigste Weg zu prüfen, ob eine Suche wirklich die gemeinten Personen zurückgibt, ist also, sie mit limit: 1 auszuführen.

{ "seniority": "VP", "department": "Sales", "industry": "Computer Software", "country": "United States", "limit": 1 }

Ein Record kostet einen Search-Record aus deinem Fair-Use-Pool. Dieselbe Query mit limit: 25, fünf Seiten tief gelaufen, kostet 125. Und wenn ein Filterwert falsch geschrieben war, sich ein department / functional_area-Paar widersprochen hat oder city einen Vorort getroffen hat, den du nicht wolltest, sind alle 125 auf die falsche Zielgruppe verpulvert und lassen sich nicht erstatten.

Lies drei Dinge aus dem einzelnen Ergebnis ab, bevor du weiter aufmachst:

• results.total: Ist die Zielgruppe so groß wie erwartet? Ein Total von 0 oder 3 heißt, dass ein Filter falsch ist, nicht dass der Markt leer ist.
• Der Record selbst: Passt diese Person tatsächlich zu deiner Absicht? Prüfe title, seniority, Standort und Arbeitgeber gegen das, was du gefragt hast.
• business_email und business_email_risk_score: Wenn du suchst, um zu mailen, bestätige, dass die E-Mails vorhanden und gut genug bewertet sind, um sie in Menge zu ziehen.

Erst wenn alle drei stimmen, solltest du mit einem größeren limit neu starten und paginieren.

Search-Records werden getrennt von Enrichment-Records gedeckelt und pro zurückgegebenem Record verbraucht, in einem rollierenden 5-Stunden-Fenster. Eine einzige ungeprüfte limit: 25-Schleife kann einen spürbaren Anteil des Plan-Pools verbrennen, bevor du merkst, dass die Filter falsch waren. Siehe Rate Limits.

Filter sind kostenlose Präzision

Die Suchkosten werden von der Freitext-query getrieben, nicht von den daran gehängten Filtern.

Query-Form	Geschwindigkeit und Präzision
query allein	Langsamer und ungenauer
query + beliebig viele Filter	Langsamer, aber präziser
Filter allein, keine query	~40x schneller und präziser

Daraus folgen zwei Regeln.

Sende nie eine nackte query. country, seniority oder alles andere anzuhängen kostet nichts und schränkt das Ergebnis scharf ein. Ein Call nur mit query ist die ungenaueste verfügbare Form und nicht günstiger als eine gefilterte.

Lass query ganz weg, wenn Filter die gesamte Absicht tragen können. “VPs of sales bei US-Softwarefirmen” ist vollständig über seniority, department, industry und country ausdrückbar. Als reine Filtersuche läuft das ~40x günstiger als dieselbe Anfrage als Freitext formuliert.

Das betrifft die Ausführungskosten, nicht die Abrechnung. Tokens werden pro zurückgegebenem Record berechnet, unabhängig von der Query-Form. Eine günstigere Query liefert schneller und belastet die Suchkapazität weniger, ändert aber nicht, was dir berechnet wird.

Wenn du nur Text hast, füge ein country hinzu

country ist zu ~99% gefüllt, die höchste Füllrate aller Filter. Es an eine Freitextsuche zu hängen verwirft fast keine legitimen Treffer und entfernt zugleich alles aus anderen Märkten. Es ist die günstigste verfügbare Präzision und der Standardfilter, zu dem du greifst, wenn du sonst nichts hast.

{ "query": "Account Executive", "country": "United States" }

Pack das Richtige in query

query ist eine Volltextsuche über full_name, first_name, last_name, Firmenname, title (~85% gefüllt) und headline (~65% gefüllt). Mehrwort-Queries verteilen die Terme über die Felder: "John Smith" matcht first_name: John und last_name: Smith statt nur eines von beiden.

Das gehört in query	Nutze stattdessen einen eigenen Filter
Namen, "Jane Doe"	Land, Bundesland, Stadt
Rollen- und Funktions-Keywords, "Account Executive", "Head of Sales"	Seniorität (VP, Director, C Suite)
Headline-Phrasen, "B2B sales leader"	Branche, Abteilung, Firmengröße, Umsatz

Eine Firma in query zu nennen verwässert sie über das Name- und das Title-Feld. Nutze company oder company_domain, um auf einen Arbeitgeber einzugrenzen.

Kenne die Füllrate jedes Filters

Jeder Exact-Match-Filter verwirft stillschweigend Records, bei denen das Feld leer ist. Drei dünn gefüllte Filter zu stapeln kann eine tragfähige Zielgruppe auf null schrumpfen.

Filter	Füllrate	Hinweise
country	~99%	Der zuverlässigste verfügbare Filter
query → title	~85%
query → headline	~65%
seniority	~60%
industry	~60%
department / functional_area	~60%	Gemeinsam befüllt, nutze eins oder das andere, nie beide
naics_code	~50%
linkedin_industry	~50%

department und functional_area teilen sich dieselben zugrunde liegenden Daten, dieselben Dokumentzahlen und dieselben Werte. Auf beiden zu filtern schränkt nichts ein und riskiert, dass du dir selbst widersprichst. Wähle eins.

Wähle deine Branchen-Granularität

Drei Filter beschreiben Branche in unterschiedlicher Auflösung. Wähle den, der zu deinem tatsächlichen Targeting passt.

Filter	Vokabular	Nutze, wenn
industry	21 breite Buckets	Du in Kategorien wie “Software” oder “Healthcare” denkst
linkedin_industry	LinkedIns eigene ~150 Labels	Du eine Nische brauchst, die die breiten Buckets nicht ausdrücken, "Wellness and Fitness Services", "Staffing and Recruiting"
naics_code	Volle NAICS-Hierarchie	Du standardisierte Codes brauchst oder die Breite präzise steuern willst

naics_code funktioniert auf jeder Hierarchieebene. Ein 2-stelliger Sektor ist breit ("54" = Professional Services), ein 6-stelliger Code ist chirurgisch ("541120" = Offices of Notaries). Kürze den Code, um das Netz zu weiten.

Standort richtig setzen

country, state und city filtern alle den Standort der Person und verlangen alle exakt gespeicherte Werte.

• Nutze volle englische Namen, keine Abkürzungen, "Texas", nicht "TX".
• "UK" und "HK" existieren als schmutzige Werte in den Daten. Bevorzuge "United Kingdom" und "Hong Kong".
• Städtenamen wiederholen sich über Regionen. Kombiniere mit state oder country, um sie zu disambiguieren, city: "Portland", state: "Oregon".
• city matcht die exakt gespeicherte Stadt, nicht ihre Vororte. Für Metro-Abdeckung filtere stattdessen auf state oder country.

Nach Firmengröße targeten, ohne eine Firma zu nennen

employee_range und revenue_range bei search_people filtern auf den aktuellen Arbeitgeber der Person. So findest du Personen bei Firmen einer bestimmten Größe oder eines bestimmten Umsatzes, ohne selbst eine Firma angeben zu müssen.

{ "seniority": "VP", "employee_range": "51-200", "country": "United States" }

Beide nutzen dasselbe Vokabular wie search_companies. Legacy-Werte ("Small", "Mid-Market", "Enterprise", "Unknown") existieren, haben aber weit dünnere Abdeckung. Bevorzuge die numerischen Ranges.

Exakte Strings exakt matchen

Jeder Filter außer query ist ein Exact-Match. Der häufigste Fehler ist ein Beinahe-Treffer bei Groß-/Kleinschreibung oder Leerzeichen:

• "C Suite" hat ein Leerzeichen, keinen Bindestrich.
• "Marketing & Advertising" nutzt ein kaufmännisches Und.
• "Medical & Health" nutzt ein kaufmännisches Und.
• "5001+" und "$500k - $1M" müssen Zeichen für Zeichen matchen.

E-Mails kommen in der Suche zurück

search_people-Ergebnisse enthalten bereits business_email und den zugehörigen business_email_risk_score. Für Kontakte, bei denen die Suche eine E-Mail zurückgibt, brauchst du keinen nachgelagerten Enrichment-Call. Siehe Gültige E-Mails bekommen dazu, was die Grades bedeuten.

Bewusst paginieren

Ergebnisse sind gerankt. Ein höherer _score bedeutet einen stärkeren Match, also ist die erste Seite die beste Seite.

Limit
Ergebnisse pro Call	25 max, 10 Standard
Ergebnisse pro Call (Free-Plan)	5 max
Free-Plan Lifetime-Search-Records	100

Jede Antwort trägt results.total, die Zahl der passenden Records über alle Seiten. Lies sie, bevor du paginierst, um zu entscheiden, ob die Suche das Durchlaufen wert ist, und erhöhe dann offset um dein limit. Der limit: 1-Test oben liefert dir dieses Total zum Preis eines einzigen Records.

Verwandt

• Nach Firmen suchen: Erst Accounts qualifizieren, dann Personen bei ihnen finden.
• Gültige E-Mails bekommen: Einen Kontakt in eine zustellbare Adresse verwandeln.