Personensuche

Mit der Personensuche-API durchsuchst du die Kontaktdatenbank von Hi Walter 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_people

Authentifizierung

Übergib deinen API-Schlüssel als Bearer-Token im Authorization-Header. Schlüssel folgen dem Format hw_XXXXXXXXXXX.

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: “John Smith” trifft first_name: John UND last_name: Smith, 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: “United States”, 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: “Hi Walter”
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. Top-Werte nach Volumen: “United States”, “India”, “United Kingdom”, “Brazil”, “Canada”, “France”, “Mexico”, “Australia”, “China”, “Spain”, “Netherlands”, “Italy”, “Indonesia”, “Germany”, “Philippines”, “Turkey”, “South Africa”, “Saudi Arabia”, “Argentina”, “Singapore”, “United Arab Emirates”, “Colombia”, “South Korea”, “Malaysia”, “Poland”, “Belgium”, “Switzerland”, “Ireland”, “Sweden”, “Denmark”, “Norway”, “Austria”, “Portugal”, “Israel”, “New Zealand”, “Finland”, “Greece”, “Hungary”, “Romania”, “Ukraine”. Nutze den vollständigen englischen Ländernamen. Beispiel: “United States”
state	string	Exakter Filter auf Bundesland oder Region der Person. Muss exakt mit dem gespeicherten Wert übereinstimmen: vollständige Namen in Standard-Großschreibung, keine Abkürzungen (“Texas”, nicht “TX”). Kombiniere für Präzision mit country. Beispiel: “Texas”
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 state und/oder country, z. B. city: “Portland”, state: “Oregon”. Trifft nur die exakt gespeicherte Stadt, nicht deren Vororte: für eine Metropolregion-Suche bevorzuge state oder country. Beispiel: “Austin”
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
naics_code	string	Exakter Filter auf den NAICS-Branchencode des aktuellen Arbeitgebers der Person (~50 % befüllt). Funktioniert auf jeder Ebene der Hierarchie, vom 2-stelligen Sektor (“23” = Construction, “54” = Professional Services) bis zur 6-stelligen nationalen Industrie (“541120” = Offices of Notaries, “511210” = Software Publishers). Nutze einen kurzen Code für breites Branchen-Targeting und einen längeren Code für Präzision. Der standardisierteste verfügbare Branchenfilter: bevorzuge ihn gegenüber industry, wenn du feingranulares Targeting brauchst. Beispiel: “541120”
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

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": "United States",
  "seniority": "Senior",
  "limit": 10,
  "offset": 0
}
'

Antwort

{
  "results": {
    "results": [
      {
        "title": "Senior Associate - Technical Director",
        "company": {
          "name": "Hi Walter",
          "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": "United States",
        "headline": "Senior Associate - Technical Director @ Hi Walter",
        "full_name": "John Smith",
        "last_name": "Smith",
        "seniority": "Senior",
        "first_name": "John",
        "linkedin_url": "https://linkedin.com/in/john-smith-123",
        "business_email": "john.smith@example.com",
        "business_email_risk_score": "A",
        "current_industry": "Information Technology",
        "linkedin_slug": "john-smith-123",
        "_id": "john-smith-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.