Personensuche
Mit der Personensuche-API durchsuchst du die Kontaktdatenbank von HiWalter nach Personen anhand von Name, Position, Unternehmen, Branche, Land, Seniorität oder Abteilung.
Nutze query für die Freitextsuche über Name, Unternehmen, Titel und Headline (hier gehören Namen und Rollen-Keywords hin). Mit den Filtern (country, seniority, industry, department oder functional_area) grenzt du die Ergebnisse weiter ein. Die Kombination aus query und Filtern liefert dir die präzisesten Treffer. Jedes Ergebnis kommt bewertet zurück: Ein höherer _score bedeutet einen stärkeren Treffer.
Nutze diesen Endpunkt, um:
- gezielte Lead-Listen für den Outbound-Vertrieb aufzubauen
- Entscheider bei bestimmten Zielunternehmen zu identifizieren
- Outbound-Sequenzen mit verifizierten Kontaktdaten zu befüllen
Fair-Use-Richtlinie: Dieser Endpunkt unterliegt unserer Fair-Use-Richtlinie für die Suche.
POST https://api.hiwalter.de/api/v1/tools/search_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 |
|---|---|---|
query | string | Freitextsuche über full_name, first_name, last_name, Unternehmensname, title (~85 % befüllt) und headline (~65 % befüllt) mit feldübergreifendem Abgleich. Mehrwort-Anfragen verteilen die Begriffe über die Felder: “Max Mustermann” trifft first_name: Max UND last_name: Mustermann, statt zu verlangen, dass ein einzelnes Feld den ganzen String enthält. Positionen und Rollen-Keywords werden sowohl gegen das Feld title (z. B. “Account Executive”, “Head of Sales”) als auch gegen headline (z. B. “B2B sales leader”) abgeglichen. Für die Senioritätsstufe (VP, Director, C-Suite) nutze stattdessen den Filter seniority. Dieses Feld eignet sich am besten für konkrete Rollen- oder Funktions-Keywords, kombiniert mit weiteren Filtern für Präzision, z. B. query: “Account Executive”, country: “Germany”, seniority: “Senior”. Kategoriale Werte wie country oder seniority gehören in ihre eigenen Filter-Parameter statt in dieses Feld. |
company | string | Filter auf den Unternehmensnamen: begrenzt die Ergebnisse auf Personen, deren Arbeitgebername passt. Analysierter Abgleich: Jedes Wort, das du angibst, muss im Unternehmensnamen vorkommen, zusätzliche Wörter im gespeicherten Namen sind also unproblematisch (“Acme” trifft “Acme Corporation”). Nutze dies, wenn du einen Unternehmensnamen, aber nicht die Domain hast; wenn du die Domain hast, bevorzuge company_domain, das präziser ist. Beispiel: “HiWalter” |
company_domain | string | Filter auf die Unternehmensdomain: begrenzt die Ergebnisse auf Personen beim Unternehmen mit dieser Website-Domain. Vollständige URLs werden automatisch normalisiert (“https://www.acme.com/about” wird zu “acme.com”), du musst also weder Protokoll noch Pfad selbst entfernen. Der präziseste Weg, ein einzelnes Unternehmen anzusprechen: bevorzuge ihn gegenüber company, wann immer du die Domain kennst. Beispiel: “hiwalter.de” |
country | string | Exakter Filter auf den Ländernamen (~99 % befüllt, zuverlässigster Filter). Muss exakt mit dem gespeicherten Wert übereinstimmen. HiWalter deckt den deutschsprachigen Raum ab, in aller Regel filterst du also auf "Germany" (der Standardwert). Für DACH-weite Suchen kombinierst du mit "Austria" und "Switzerland". Nutze den vollständigen englischen Ländernamen, "Germany", nicht "DE". Beispiel: “Germany” |
city | string | Exakter Filter auf die Stadt der Person. Muss exakt mit dem gespeicherten Wert in Standard-Großschreibung übereinstimmen. Städtenamen wiederholen sich über Regionen hinweg, kombiniere daher zur Eindeutigkeit mit country, z. B. city: “München”, country: “Germany”. Trifft nur die exakt gespeicherte Stadt, nicht deren Vororte: für eine überregionale Suche bevorzuge country. Beispiel: “Berlin” |
seniority | enumstring | Exakter Filter auf die Senioritätsstufe (~60 % befüllt). Muss exakt einem der aufgezählten Werte entsprechen, inklusive des Leerzeichens in “C Suite” (kein Bindestrich). Verfügbare Optionen: Intern, Entry, Senior, Manager, Director, VP, Head, C Suite, Owner, Partner |
industry | enumstring | Exakter Branchenfilter (~60 % befüllt). Muss exakt einem der aufgezählten Werte entsprechen, inklusive Groß-/Kleinschreibung und Zeichensetzung (z. B. das kaufmännische Und in “Marketing & Advertising”). Verfügbare Optionen: Information Technology, Professional and Business Services, Finance and Banking, Education, Health and Pharmaceuticals, Manufacturing, Government and Public Administration, Retail, Food and Beverage, Creative Arts and Entertainment, Non-Profit and Social Services, Transportation and Logistics, Construction, Tourism and Hospitality, Energy, Marketing & Advertising, Telecommunications, Real Estate, Automotive, Media and Publishing, Agriculture |
department | enumstring | Exakter Abteilungsfilter (~60 % befüllt). Teilt sich die zugrunde liegenden Daten mit functional_area: nutze das eine oder das andere, nicht beide. Muss exakt einem der aufgezählten Werte entsprechen, inklusive Groß-/Kleinschreibung und Zeichensetzung (z. B. das kaufmännische Und in “Medical & Health”). Verfügbare Optionen: Operations, Sales, Information Technology, Education, Engineering, Finance, Medical & Health, Marketing, Human Resources, Design, Consulting, Legal |
functional_area | enumstring | Exakter Filter auf den Funktionsbereich (~60 % befüllt). Teilt sich die zugrunde liegenden Daten mit department: nutze das eine oder das andere, nicht beide. Verfügbare Optionen: Operations, Sales, Information Technology, Education, Engineering, Finance, Medical & Health, Marketing, Human Resources, Design, Consulting, Legal |
employee_range | enumstring | Exakter Filter auf die Mitarbeiterzahl-Spanne des aktuellen Arbeitgebers der Person: findet Personen bei Unternehmen einer bestimmten Größe, ohne ein konkretes Unternehmen nennen zu müssen. Die Werte sind feste Spannen (z. B. “51-200”, “1001-5000”). Legacy-Werte (“Small”, “Mid-Market”, “Enterprise”, “Unknown”) existieren ebenfalls in älteren Datensätzen, haben aber deutlich weniger Abdeckung als die numerischen Spannen. Kombiniere mit weiteren Filtern, z. B. seniority: “VP”, employee_range: “51-200”. Verfügbare Optionen: 1-10, 11-20, 21-50, 51-200, 201-500, 501-1000, 1001-5000, 5001+, Small, Mid-Market, Enterprise, Unknown |
revenue_range | enumstring | Exakter Filter auf die Jahresumsatz-Spanne des aktuellen Arbeitgebers der Person: findet Personen bei Unternehmen eines bestimmten Umsatzes, ohne ein konkretes Unternehmen nennen zu müssen. Die Werte sind feste Spannen. “€1 - €1M” ist ein Legacy-Format, gleichbedeutend mit “€500k - €1M”, aber mit deutlich weniger Datensätzen. Verfügbare Optionen: Below €500k, €500k - €1M, €1M - €5M, €5M - €10M, €10M - €20M, €20M - €50M, Above €50M, €50M - €100M, €100M - €250M, €250M - €500M, €500M - €1B, €1B - €2.5B, €2.5B - €5B, Over €5B, €1 - €1M |
linkedin_industry | string | Exakter Filter auf das LinkedIn-Branchenlabel des aktuellen Arbeitgebers der Person (~50 % befüllt). Nutzt das rund 150 Werte umfassende LinkedIn-eigene Branchenvokabular, das weit feingranularer ist als die 21 Buckets in industry. Muss exakt mit dem gespeicherten Label in Standard-Großschreibung übereinstimmen, z. B. “Software Development”, “Hospitality”, “Legal Services”, “Wellness and Fitness Services”, “Construction”, “Staffing and Recruiting”. Nutze dies, wenn eine Nischenbranche nicht über die breiten industry-Buckets ausgedrückt werden kann. Beispiel: “Software Development” |
limit | integer | Anzahl der zurückzugebenden Ergebnisse (Standard: 10, max: 25). Zulässiger Bereich: 1 <= x <= 25. |
offset | integer | Anzahl der zu überspringenden Ergebnisse für die Paginierung (Standard: 0). Nutze es zusammen mit limit, um durch die Ergebnisse zu blättern, z. B. offset: 10 für die zweite Seite mit 10 Ergebnissen. |
Beispiel
Section titled “Beispiel”curl --request POST \ --url https://api.hiwalter.de/api/v1/tools/search_people \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "query": "Account Executive", "country": "Germany", "seniority": "Senior", "limit": 10, "offset": 0}'Antwort
Section titled “Antwort”{ "results": { "results": [ { "title": "Senior Associate - Technical Director", "company": { "name": "HiWalter", "size": "57", "revenue": "1200000000", "industry": "Information Technology", "logo_url": "https://cdn.mixrank.com/md5/0bb6181a215bac707d7af3276be5XXXXX", "website_url": "https://hiwalter.de", "linkedin_url": "https://linkedin.com/company/hiwalter" }, "country": "Germany", "headline": "Senior Associate - Technical Director @ HiWalter", "full_name": "Max Mustermann", "last_name": "Mustermann", "seniority": "Senior", "first_name": "Max", "linkedin_url": "https://linkedin.com/in/max-mustermann-123", "business_email": "max.mustermann@example.com", "business_email_risk_score": "A", "current_industry": "Information Technology", "linkedin_slug": "max-mustermann-123", "_id": "max-mustermann-123", "_score": 9.1714 } ], "total": 278 }, "status": "ok", "metadata": { "fair_use": { "records_remaining_5h": 179999, "records_reset_5h": "2026-07-15T18:53:16Z", "records_remaining_1w": 899999, "records_reset_1w": "2026-07-22T13:53:16Z" } }}| Feld | Typ | Beschreibung |
|---|---|---|
results.results | array | Liste der gefundenen Personen. |
results.results[].title | string | Aktuelle Positionsbezeichnung der Person. |
results.results[].company | object | Firmografische Daten zum aktuellen Arbeitgeber der Person. |
results.results[].company.name | string | Name des Unternehmens. |
results.results[].company.size | string | Mitarbeiterzahl des Unternehmens. |
results.results[].company.revenue | string | Jahresumsatz des Unternehmens. |
results.results[].company.industry | string | Branche des Unternehmens. |
results.results[].company.logo_url | string | URL zum Logo des Unternehmens. |
results.results[].company.website_url | string | Website-URL des Unternehmens. |
results.results[].company.linkedin_url | string | LinkedIn-URL des Unternehmens. |
results.results[].country | string | Land der Person. |
results.results[].headline | string | LinkedIn-Headline der Person. |
results.results[].full_name | string | Vollständiger Name der Person. |
results.results[].last_name | string | Nachname der Person. |
results.results[].seniority | string | Senioritätsstufe der Person. |
results.results[].first_name | string | Vorname der Person. |
results.results[].linkedin_url | string | LinkedIn-Profil-URL der Person. |
results.results[].business_email | string | Geschäftliche E-Mail-Adresse der Person. |
results.results[].business_email_risk_score | string | Risiko-Score der geschäftlichen E-Mail-Adresse. |
results.results[].current_industry | string | Aktuelle Branche der Person. |
results.results[].linkedin_slug | string | LinkedIn-Slug der Person. |
results.results[]._id | string | Eindeutige Kennung des Datensatzes. |
results.results[]._score | number | Relevanz-Score des Treffers; ein höherer Wert bedeutet einen stärkeren Treffer. |
results.total | integer | Gesamtzahl der Personen, die auf die Anfrage passen. |
status | string | Status der Anfrage, z. B. “ok”. |
metadata.fair_use.records_remaining_5h | integer | Verbleibende Datensätze im aktuellen 5-Stunden-Fenster. |
metadata.fair_use.records_reset_5h | string | Zeitpunkt, zu dem das 5-Stunden-Kontingent zurückgesetzt wird. |
metadata.fair_use.records_remaining_1w | integer | Verbleibende Datensätze im aktuellen 1-Wochen-Fenster. |
metadata.fair_use.records_reset_1w | string | Zeitpunkt, zu dem das 1-Wochen-Kontingent zurückgesetzt wird. |