Firmen segmentieren (segment_companies)
Eine Liste mit 2.000 Firmen ist selten ein Markt, sondern meist mehrere. segment_companies gruppiert deine Firmen anhand ihres Website-Inhalts in Cluster und benennt jedes Segment. So schreibst du pro Segment eine eigene, passende Mail statt einer für alle.
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:
- eine Discovery-Liste in Kampagnen aufzuteilen (ein Segment = ein Mail-Winkel)
- deine Bestandskunden zu clustern und für jedes Cluster Lookalikes zu suchen
- Ausreißer-Cluster zu erkennen und auszuschließen
Fair-Use-Richtlinie: Dieser Endpunkt unterliegt unserer Fair-Use-Richtlinie für die Suche.
POST https://api.hiwalter.de/api/v1/tools/segment_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 ist Pflicht.
| Parameter | Typ | Beschreibung |
|---|---|---|
domains | string[] | Zu segmentierende Firmen, mindestens 10, bis zu 10.000. |
list_id | string | Alternativ: Firmen aus einer gespeicherten Liste. |
max_segments | integer | Maximale Anzahl Segmente (2-20, Standard: 8). |
save_segments_as_lists | boolean | Speichert jedes Segment als eigene Liste. Standard: false. |
Nach Abschluss liefert Task-Status abrufen:
{ "segments": [ { "segment_id": 1, "label": "Verpackungs- und Abfüllanlagen", "description": "Sondermaschinenbauer für Verpackung, Abfüllung und Etikettierung in der Lebensmittelindustrie.", "size": 412, "top_domains": [ "mueller-maschinenbau.de", "pack-tech.de" ], "list_id": "lst_seg_1" } ]}Beispiel
Section titled “Beispiel”curl --request POST \ --url https://api.hiwalter.de/api/v1/tools/segment_companies \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "list_id": "lst_maschinenbau_nrw", "max_segments": 6, "save_segments_as_lists": true}'Antwort
Section titled “Antwort”{ "task_id": "tsk_2c81de", "status": "queued", "total": 1840}| Feld | Typ | Beschreibung |
|---|---|---|
task_id | string | ID des Tasks. |
segments[].label | string | Name des Segments. |
segments[].description | string | Was die Firmen in diesem Segment verbindet. |
segments[].size | integer | Anzahl Firmen im Segment. |
segments[].top_domains | string[] | Die typischsten Firmen des Segments, ideal als Seeds für Firmen entdecken. |
segments[].list_id | string | Liste des Segments, wenn save_segments_as_lists gesetzt war. |