Firmen recherchieren (research_companies)
research_companies ist dein Recherche-Assistent im Massenbetrieb. Du stellst eine oder mehrere Fragen, HiWalter beantwortet sie für jede Firma einzeln auf Basis ihrer Website.
Ja/Nein- und Auswahlfragen kommen als typisierte Spalten zurück ("Ja"/"Nein" oder einer deiner Werte), jeweils mit Konfidenz. Offene Fragen bekommen einen kurzen Freitext.
Dieser Endpunkt arbeitet asynchron: Du bekommst sofort eine task_id zurück und fragst das Ergebnis mit Task-Status abrufen ab, am besten alle 5 Sekunden. Zwischenergebnisse stehen schon während der Verarbeitung in partial_results.
Nutze diesen Endpunkt, um:
- Signale zu prüfen, die kein Filter abbildet (“Suchen sie gerade Vertriebler?”, “Gibt es einen Online-Shop?”)
- Personalisierungs-Hooks für die erste Mail-Zeile zu erzeugen
- Listen nach Kaufbereitschaft zu priorisieren
Fair-Use-Richtlinie: Dieser Endpunkt unterliegt unserer Fair-Use-Richtlinie für die Suche.
POST https://api.hiwalter.de/api/v1/tools/research_companiesAuthentifizierung
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. domains oder list_id sowie questions sind Pflicht.
| Parameter | Typ | Beschreibung |
|---|---|---|
domains | string[] | Zu recherchierende Firmen, bis zu 10.000. |
list_id | string | Alternativ: Firmen aus einer gespeicherten Liste. |
questions | object[] | Bis zu 10 Fragen. Jede Frage hat key, question und optional type (yes_no, choice, text) und bei choice die erlaubten options. Ohne type erkennt HiWalter den Typ selbst. |
context | enumstring | Welche Daten pro Firma gelesen werden. website (Standard): Profil plus Website-Text. profile: nur Firmenprofil, schneller. web: zusätzlich Live-Websuche, z. B. für Stellenanzeigen oder News. |
include_confidence | boolean | Gibt pro typisierter Antwort eine Konfidenz (High, Medium, Low) zurück. Standard: true. |
Nach Abschluss liefert Task-Status abrufen pro Firma:
{ "domain": "mueller-maschinenbau.de", "answers": { "hiring_sales": { "value": "Ja", "confidence": "High" }, "export": { "value": "Europa", "confidence": "Medium" }, "hook": { "value": "Sucht seit September einen Vertriebsleiter für den Export nach Osteuropa." } }}Beispiel
Section titled “Beispiel”curl --request POST \ --url https://api.hiwalter.de/api/v1/tools/research_companies \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "list_id": "lst_maschinenbau_nrw", "context": "web", "questions": [ { "key": "hiring_sales", "question": "Sucht die Firma gerade Mitarbeiter im Vertrieb?", "type": "yes_no" }, { "key": "export", "question": "Wohin exportiert die Firma hauptsächlich?", "type": "choice", "options": [ "Nur DACH", "Europa", "Weltweit" ] }, { "key": "hook", "question": "Was ist ein konkreter, aktueller Aufhänger für eine erste Mail? Ein Satz.", "type": "text" } ]}'Antwort
Section titled “Antwort”{ "task_id": "tsk_91bb02", "status": "queued", "total": 1840}| Feld | Typ | Beschreibung |
|---|---|---|
task_id | string | ID des Tasks. |
results[].answers | object | Antworten pro Frage, unter dem jeweiligen key. |
results[].answers.*.value | string | Antwort: "Ja"/"Nein", einer der options oder Freitext. |
results[].answers.*.confidence | string | Konfidenz bei typisierten Fragen. Low heißt: unklar, nicht darauf verlassen. |
- Ja/Nein-Fragen sind am zuverlässigsten. Zerlege komplexe Fragen lieber in mehrere einfache.
context: "web"nur nutzen, wenn die Antwort nicht auf der Website steht (Stellenanzeigen, News). Es ist langsamer.