Firmen und Kontakte finden

Hi Walter hat zwei Such-Endpunkte: einen für Firmen und einen für Kontakte. Beide akzeptieren dieselben Kern-Filter und liefern nach Relevanz sortierte Ergebnisse. Nutze sie, wenn du Datensätze finden willst, die zu einem Profil passen, statt eine bestimmte Person oder Firma anzureichern, die du bereits kennst.

Wenn du bereits eine LinkedIn-URL, eine E-Mail oder eine IP-Adresse hast und diese anreichern willst, siehe Ich habe X, ich will Y.

Suchergebnisse sind auf 25 pro Aufruf begrenzt (limit max 25, Standard 10). Konten im Free-Tarif sind auf 5 pro Aufruf begrenzt (limit max 5) und erhalten insgesamt 100 Suchergebnisse, lebenslang. Nutze limit und offset gemeinsam, um durch größere Ergebnismengen zu paginieren. Beispiele findest du unten unter Paginierung. Keiner der Endpunkte unterstützt einen Gründungsjahr-Filter. Branchen- und Bereichs-Filter nutzen feste Aufzählungen, die akzeptierten Werte findest du in der API-Referenz.

Verfügbare Filter

Die beiden Endpunkte teilen sich den größten Teil ihres Vokabulars. industry, employee_range, revenue_range, naics_code, linkedin_industry, country, state, limit und offset erscheinen bei beiden; der Rest ist endpunktspezifisch.

search_companies

Filter	Was er macht	Hinweise
`query`	Freitext-Suche über den Firmennamen	Nicht für Domain, Branche oder Größe nutzen, dafür gibt es die dedizierten Filter
`domain`	Exakter Abgleich der Firmen-Domain	Vollständige URLs werden automatisch normalisiert (`https://www.acme.com/about` → `acme.com`). Bevorzuge dies gegenüber `query`, wenn du eine bekannte Domain hast
`industry`	Filtert nach Branche	Feste Aufzählung, akzeptierte Werte siehe Search Company Profiles
`linkedin_industry`	Filtert nach LinkedIns Branchen-Label	LinkedIns eigenes Vokabular mit ~150 Werten, feiner granuliert als `industry`
`naics_code`	Filtert nach NAICS-Branchencode	Trifft auf jeder Hierarchieebene, vom 2-stelligen Sektor bis zur 6-stelligen nationalen Branche
`employee_range`	Filtert nach Mitarbeiterzahl-Band	Feste Aufzählung, akzeptierte Werte siehe Search Company Profiles
`revenue_range`	Filtert nach Jahresumsatz-Band	Feste Aufzählung, akzeptierte Werte siehe Search Company Profiles
`country`	Exakter Länder-Filter nach Name	Firmenstandort wird aus dem Team abgeleitet, siehe Hinweis unten
`state`	Exakter Bundesland- oder Regions-Filter	Vollständige Namen, keine Abkürzungen. Kombiniere mit `country`
`limit`	Anzahl der zurückgegebenen Ergebnisse	Max 25 pro Aufruf, Standard 10 (Free-Tarif: max 5)
`offset`	Anzahl der übersprungenen Ergebnisse	Mit `limit` zum Paginieren nutzen

country und state bei search_companies beschreiben, wo das Team der Firma sitzt. Das ist für die kleinen Firmen, die den Index dominieren, präzise, aber große Multinationals werden einem einzelnen ihrer Büros zugeordnet. Kombiniere den Standort mit anderen Filtern, statt dich bei globalen Firmen allein darauf zu verlassen.

search_people

Filter	Was er macht	Hinweise
`query`	Freitext-Suche über Name, Firma, Titel und Headline	Namen und Rollen-Stichwörter hier eintragen
`company`	Filtert nach Firmenname	Grenzt auf den Arbeitgeber der Person ein. Jedes von dir angegebene Wort muss im Namen vorkommen (`Acme` trifft `Acme Corporation`)
`company_domain`	Exakter Abgleich der Firmen-Domain	Vollständige URLs werden automatisch normalisiert. Bevorzuge dies gegenüber `company`, wenn du eine bekannte Domain hast
`country`	Exakter Länder-Filter nach Name	Zuverlässigster Filter (~99% gefüllt). Muss dem gespeicherten Wert entsprechen
`state`	Exakter Bundesland- oder Regions-Filter	Vollständige Namen, keine Abkürzungen: `Texas`, nicht `TX`
`city`	Exakter Städte-Filter nach Name	Trifft die exakt gespeicherte Stadt, nicht ihre Vororte. Kombiniere mit `state` / `country` zur Eindeutigkeit
`seniority`	Exakte Senioritätsstufe	Feste Aufzählung, akzeptierte Werte siehe Search Business Profiles
`industry`	Filtert nach Branche	Feste Aufzählung, akzeptierte Werte siehe API-Referenz
`linkedin_industry`	Filtert nach LinkedIns Branchen-Label	Vokabular mit ~150 Werten, feiner granuliert als `industry`
`naics_code`	Filtert nach NAICS-Branchencode	Trifft auf jeder Hierarchieebene
`department` / `functional_area`	Team- oder Funktions-Filter	Aus derselben Datenquelle gemeinsam befüllt, nutze das eine oder das andere, niemals beide
`employee_range`	Filtert nach Mitarbeiterzahl-Band des Arbeitgebers	Bezieht sich auf den aktuellen Arbeitgeber der Person
`revenue_range`	Filtert nach Umsatz-Band des Arbeitgebers	Bezieht sich auf den aktuellen Arbeitgeber der Person
`limit`	Anzahl der zurückgegebenen Ergebnisse	Max 25 pro Aufruf, Standard 10 (Free-Tarif: max 5)
`offset`	Anzahl der übersprungenen Ergebnisse	Mit `limit` zum Paginieren nutzen

Kombiniere query mit Filtern für beste Präzision: Filter anzuhängen kostet nichts extra, und eine Suche, die allein auf Filtern aufbaut, läuft weit günstiger als eine, die von Freitext getrieben wird. Die vollständige Anleitung findest du unter Personen suchen und Firmen suchen.

Ergebnisse werden nach Relevanz sortiert: ein höheres _score bedeutet einen stärkeren Treffer.

Firmen finden

Nutze search_companies, wenn dein Ergebnis eine Liste von Firmen ist. Liefert Name, Domain, Branche, Mitarbeiterzahl, Umsatz-Band, LinkedIn-URL und Follower-Zahl.

Ich will…	In Claude eingeben…	Genutzte Filter
Eine bestimmte Firma per Domain	Finde den Firmen-Datensatz für acme.com	`domain`
Firmen, die zu einem Namen passen	Finde Firmenprofile, die zu Acme passen	`query`
Firmen in einer bestimmten Branche	Finde Firmen aus dem Bereich Informationstechnologie	`industry`
Firmen nach Branche und Mitarbeiterzahl	Finde IT-Firmen mit 51–200 Mitarbeitenden	`industry`, `employee_range`
Firmen nach Branche und Umsatz	Finde Softwarefirmen mit über 50 Mio. $ Umsatz	`industry`, `revenue_range`
Firmen, die zu einem ICP passen	Finde privat gehaltene Softwarefirmen mit 201–500 Mitarbeitenden und einem Umsatz zwischen 10 Mio. $ und 50 Mio. $	`industry`, `employee_range`, `revenue_range`

Kontakte finden

Nutze search_people, wenn dein Ergebnis eine Liste von Personen ist. Liefert Name, Titel, Seniorität, LinkedIn-URL, Geschäfts-E-Mail, Firmenname und firmografische Daten.

Ich will…	In Claude eingeben…	Genutzte Filter
Alle Kontakte bei einer bestimmten Firma	Finde Kontakte bei acme.com	`company_domain`
Kontakte bei einer benannten Firma	Finde Kontakte bei Acme	`company`
Kontakte in einer bestimmten Branche	Finde Kontakte bei IT-Firmen	`industry`
Entscheider bei einer Firma	Finde Senior-Kontakte bei acme.com	`company_domain`, `seniority`
Kontakte in einem bestimmten Team	Finde Engineering-Kontakte bei acme.com	`company_domain`, `department`
Kontakte in einer Branche und einem Land	Finde Marketing-Kontakte bei Softwarefirmen in den USA	`industry`, `country`
Kontakte in einer bestimmten Stadt	Finde Vertriebskontakte in Austin, Texas	`city`, `state`
Kontakte bei Firmen einer bestimmten Größe	Finde VPs bei Firmen mit 51–200 Mitarbeitenden	`seniority`, `employee_range`
Kontakte, die zu einem ICP passen	Finde Senior-Engineering-Kontakte bei IT-Firmen in den USA	`industry`, `seniority`, `department`, `country`

Um Kontakte nach Firmengröße oder Umsatz zu targeten, filtere direkt auf search_people: employee_range und revenue_range beziehen sich auf den aktuellen Arbeitgeber der Person, du kannst also Personen bei Firmen einer bestimmten Größe finden, ohne eine Firma zu benennen. Ketten über search_companies nur, wenn du zusätzlich die Firmen-Datensätze selbst willst.

Paginierung

Jeder Aufruf liefert maximal 25 Ergebnisse (5 im Free-Tarif). Um mehr abzurufen, erhöhe offset bei jedem folgenden Aufruf um 25 (um 5 im Free-Tarif). Konten im Free-Tarif haben eine lebenslange Obergrenze von insgesamt 100 Suchergebnissen, Paginierung ist also nur bis zu dieser Grenze nützlich.

Die Gesamtzahl der passenden Datensätze wird im Feld total jeder Antwort zurückgegeben. Nutze diese, um zu bestimmen, wie viele Seiten es gibt, bevor du mit dem Paginieren beginnst.

Nutzung mit MCP

Sobald Hi Walter mit Claude verbunden ist, beschreibe, was du willst, und Claude ruft den richtigen Such-Endpunkt mit den richtigen Filtern auf.

Exakte Firmensuche:

Schlage den Firmen-Datensatz für acme.com nach

ICP-Firmenliste:

Finde Softwarefirmen mit 51–200 Mitarbeitenden und einem Umsatz zwischen 10 Mio. $ und 50 Mio. $

ICP-Kontaktliste:

Finde Senior-Kontakte bei IT-Firmen in den USA

Paginierter Abruf:

Finde Senior-Kontakte bei IT-Firmen in den USA. Hole die ersten 25 und rufe dann weiter die nächste Seite ab, bis du 100 Ergebnisse hast.

Paginierung per Offset/Skip:

Finde Senior-Kontakte bei IT-Firmen in den USA. Setze den Offset auf 50 und rufe dann weiter die nächste Seite ab, bis du 100 weitere Ergebnisse hast.

Nutzung mit der API

Alle Such-Anfragen folgen derselben Form. Übergib deine Filter im Request-Body und erhöhe offset zum Paginieren.

Firmen finden, die zu einem ICP passen:

const response = await fetch("https://api.hiwalter.de/api/v1/tools/search_companies", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    industry: "Computer Software",
    employee_range: "51-200",
    revenue_range: "$10M - $20M",
    limit: 25,
    offset: 0
  })
});
const data = await response.json();
// data.results.results, Array der passenden Firmen
// data.results.total, Gesamtzahl der passenden Datensätze über alle Seiten

Kontakte bei einer bestimmten Firma finden:

const response = await fetch("https://api.hiwalter.de/api/v1/tools/search_people", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    company_domain: "acme.com",
    limit: 25,
    offset: 0
  })
});
const data = await response.json();
// data.results.results, Array der passenden Kontakte
// data.results.total, Gesamtzahl der passenden Datensätze über alle Seiten

Durch Ergebnisse paginieren:

async function fetchAllResults(filters, endpoint) {
  const results = [];
  let offset = 0;
  const limit = 25;
  while (true) {
    const response = await fetch(`https://api.hiwalter.de/api/v1/tools/${endpoint}`, {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ ...filters, limit, offset })
    });
    const data = await response.json();
    const page = data.results.results;
    results.push(...page);
    if (results.length >= data.results.total || page.length < limit) break;
    offset += limit;
  }
  return results;
}

// Beispiel: alle Kontakte bei acme.com abrufen
// Hinweis: search_people grenzt über `company_domain` ein; `domain` ist der Filter von search_companies
const contacts = await fetchAllResults({ company_domain: "acme.com" }, "search_people");