API-Referenz

Lead Scout

Bisherige Google-Suchen nach neuen Leads lesen

Bisherige Lead-Scout-Suchen auflisten

GET/v1/lead-scout/searches

Scope read:leadsRecht: Lead Scout: Suchenliest

Alle Google-Suchen des Kontos, neueste zuerst, mit Suchparametern und der Zahl gefundener Leads. leads_found zählt wie die Ergebnisliste der App: fertig ausgewertet, von der KI nicht als unpassend markiert, mit Firma, Entscheider und E-Mail (dazu Telefon oder Adresse, falls gefordert), höchstens so viele wie gewünscht. Anders als die Startseite der App, die nur die letzten offenen und fertigen Suchen zeigt, kommen hier auch fehlgeschlagene. Mehrere Filter werden mit UND verknüpft.

Die Suchen entstehen in der App unter Lead Scout > Google-Suche (oder im Assistenten). Über die API lassen sie sich nur lesen: Starten kostet Websuche ohne Credits und Speichern kostet 2 Credits je Lead, beides bleibt in der App. Abfragen kostet nichts.

Jedes Mitglied mit dem Recht für den Lead Scout sieht alle Suchen des Kontos, wie in der App. Suchen, die in der App entfernt wurden, fehlen.

Query-Parameter

limitintegerab 1bis 100
Einträge pro Seite (Standard 25, höchstens 100)
cursorstringmax. 200 Zeichen
Wert aus meta.next_cursor der vorigen Seite
statusListe aus string
Ein oder mehrere Status, kommagetrennt, z. B. queued,running für alles, was noch läuft
queued running succeeded failed
list_idstring (uuid)
Nur Suchen mit dieser Zielliste
created_afterstring (date-time)
Nur Suchen, die seitdem gestartet wurden

Felder der Antwort

idstring (uuid)
ID der Suche
kindstring
Art der Suche: web ist die Google-Suche mit Auswertung der Firmenwebsites (in der App „Google-Suche“)
web
statusstring
queued wartet, running sucht und wertet Websites aus, succeeded ist fertig, failed ist gescheitert
queued running succeeded failed
querystring, kann null sein
Suchbegriff
filtersobject
Suchparameter in Kurzform
Felder anzeigen
- locationstring, kann null sein
  Ort der Suche
- industrystring, kann null sein
  Branche, null ohne Einschränkung
- countrystring, kann null sein
  Land der Google-Suche, z. B. de
- languagestring, kann null sein
  Sprache der Google-Suche, z. B. de
- time_rangestring, kann null sein
  Nur Seiten aus diesem Zeitraum (hour, day, week, month, year), null für alle Zeiten
  hour day week month year
- company_websites_onlyboolean
  Nur Unternehmenswebsites (mit Impressum), keine Verzeichnisse und Portale
- exclude_existing_leadsboolean
  Firmen, die schon als Lead im Konto stehen, wurden übersprungen
- single_decision_maker_onlyboolean
  Nur ein Entscheider je Firma
- required_dataListe aus string
  Zusätzlich verlangte Angaben: address (vollständige Adresse für Briefe), phone (Telefon). Firma, Entscheider und E-Mail sind immer Pflicht
  address phone
- domain_keywordsListe aus string
  Begriffe, die in der Domain vorkommen müssen
- exclude_keywordsstring, kann null sein
  Ausgeschlossene Begriffe
- target_audiencestring, kann null sein
  Beschreibung der Zielgruppe, gegen die die KI die Treffer geprüft hat
leads_requestedintegerab 1
Gewünschte Anzahl Leads
leads_foundintegerab 0
Gefundene Leads wie in der Ergebnisliste der App (höchstens leads_requested). Während die Suche läuft, der Stand bis jetzt
messagestring, kann null sein
Hinweis wie in der App: Grund bei failed, Erklärung wenn weniger Leads als gewünscht gefunden wurden. Nie eine technische Meldung
list_idstring (uuid), kann null sein
Zielliste, in die die App die Treffer speichert
created_bystring (uuid), kann null sein
Team-Mitglied, das die Suche gestartet hat (GET /v1/team). Die App erfasst das bisher nicht, dann null
created_atstring (date-time)
Start der Suche (ISO 8601, UTC)
updated_atstring (date-time), kann null sein
Letzte Änderung am Suchauftrag (ISO 8601, UTC)
finished_atstring (date-time), kann null sein
Ende der Suche, null solange sie wartet oder läuft

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/lead-scout/searches" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/lead-scout/searches", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/lead-scout/searches",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": [
    {
      "id": "2b8c4d6e-1f3a-4b5c-9d7e-8f0a1b2c3d4e",
      "kind": "web",
      "status": "running",
      "query": "Steuerberater",
      "filters": {
        "location": "Köln",
        "industry": "Beratung & Consulting",
        "country": "de",
        "language": "de",
        "time_range": null,
        "company_websites_only": true,
        "exclude_existing_leads": true,
        "single_decision_maker_only": true,
        "required_data": [],
        "domain_keywords": [],
        "exclude_keywords": null,
        "target_audience": null
      },
      "leads_requested": 50,
      "leads_found": 8,
      "message": null,
      "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
      "created_by": null,
      "created_at": "2026-10-18T08:02:40.117Z",
      "updated_at": "2026-10-18T08:05:03.640Z",
      "finished_at": null
    },
    {
      "id": "7d3e9b21-4c5a-4f6e-8a1b-2c3d4e5f6a7b",
      "kind": "web",
      "status": "succeeded",
      "query": "Pflegedienst",
      "filters": {
        "location": "Hamburg",
        "industry": "Gesundheitswesen",
        "country": "de",
        "language": "de",
        "time_range": null,
        "company_websites_only": true,
        "exclude_existing_leads": true,
        "single_decision_maker_only": true,
        "required_data": [
          "phone"
        ],
        "domain_keywords": [
          "pflege"
        ],
        "exclude_keywords": "Stellenangebot",
        "target_audience": "Ambulante Pflegedienste mit 10 bis 50 Mitarbeitenden"
      },
      "leads_requested": 20,
      "leads_found": 14,
      "message": "Es wurden nur 14 von 20 gewünschten Leads gefunden. Mögliche Gründe: strenge Filter (z. B. „Nur Unternehmenswebsites“, Pflicht-Telefon oder Pflicht-Adresse) oder ein kleiner lokaler Markt.",
      "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
      "created_by": null,
      "created_at": "2026-10-17T09:30:12.418Z",
      "updated_at": "2026-10-17T09:41:55.902Z",
      "finished_at": "2026-10-17T09:41:55.902Z"
    }
  ],
  "meta": {
    "request_id": "req_7f3a…",
    "next_cursor": null,
    "has_more": false
  }
}

Eine Lead-Scout-Suche mit Kennzahlen

GET/v1/lead-scout/searches/{id}

Scope read:leadsRecht: Lead Scout: Suchenliest

Eine Suche wie in der Liste, dazu die Zahlen der Ergebnisseite der App: gefundene Websites, davon nicht passende und Leads mit anderem Standort. Zum Warten auf eine laufende Suche etwa alle 10 Sekunden abfragen, bis status succeeded oder failed ist. Die Treffer selbst liefert GET /v1/lead-scout/searches/{id}/results.

Jedes Mitglied mit dem Recht für den Lead Scout sieht alle Suchen des Kontos, wie in der App. Suchen, die in der App entfernt wurden, fehlen.

Pfad-Parameter

idstring (uuid)Pflicht
ID der Suche

Felder der Antwort

idstring (uuid)
ID der Suche
kindstring
Art der Suche: web ist die Google-Suche mit Auswertung der Firmenwebsites (in der App „Google-Suche“)
web
statusstring
queued wartet, running sucht und wertet Websites aus, succeeded ist fertig, failed ist gescheitert
queued running succeeded failed
querystring, kann null sein
Suchbegriff
filtersobject
Suchparameter in Kurzform
Felder anzeigen
- locationstring, kann null sein
  Ort der Suche
- industrystring, kann null sein
  Branche, null ohne Einschränkung
- countrystring, kann null sein
  Land der Google-Suche, z. B. de
- languagestring, kann null sein
  Sprache der Google-Suche, z. B. de
- time_rangestring, kann null sein
  Nur Seiten aus diesem Zeitraum (hour, day, week, month, year), null für alle Zeiten
  hour day week month year
- company_websites_onlyboolean
  Nur Unternehmenswebsites (mit Impressum), keine Verzeichnisse und Portale
- exclude_existing_leadsboolean
  Firmen, die schon als Lead im Konto stehen, wurden übersprungen
- single_decision_maker_onlyboolean
  Nur ein Entscheider je Firma
- required_dataListe aus string
  Zusätzlich verlangte Angaben: address (vollständige Adresse für Briefe), phone (Telefon). Firma, Entscheider und E-Mail sind immer Pflicht
  address phone
- domain_keywordsListe aus string
  Begriffe, die in der Domain vorkommen müssen
- exclude_keywordsstring, kann null sein
  Ausgeschlossene Begriffe
- target_audiencestring, kann null sein
  Beschreibung der Zielgruppe, gegen die die KI die Treffer geprüft hat
leads_requestedintegerab 1
Gewünschte Anzahl Leads
leads_foundintegerab 0
Gefundene Leads wie in der Ergebnisliste der App (höchstens leads_requested). Während die Suche läuft, der Stand bis jetzt
messagestring, kann null sein
Hinweis wie in der App: Grund bei failed, Erklärung wenn weniger Leads als gewünscht gefunden wurden. Nie eine technische Meldung
list_idstring (uuid), kann null sein
Zielliste, in die die App die Treffer speichert
created_bystring (uuid), kann null sein
Team-Mitglied, das die Suche gestartet hat (GET /v1/team). Die App erfasst das bisher nicht, dann null
created_atstring (date-time)
Start der Suche (ISO 8601, UTC)
updated_atstring (date-time), kann null sein
Letzte Änderung am Suchauftrag (ISO 8601, UTC)
finished_atstring (date-time), kann null sein
Ende der Suche, null solange sie wartet oder läuft
websites_foundintegerab 0
Websites, die die Suche gefunden hat (in der App „URLs gefunden“)
not_matchingintegerab 0
Davon nicht passend: Verzeichnis, Job-Portal, kein Impressum, anderer Standort, von der KI als unpassend erkannt oder nicht lesbar (in der App „nicht passend“)
other_locationintegerab 0
Gefundene Leads mit abweichendem Standort (in der App „anderer Standort“)

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/lead-scout/searches/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/lead-scout/searches/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/lead-scout/searches/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "id": "7d3e9b21-4c5a-4f6e-8a1b-2c3d4e5f6a7b",
    "kind": "web",
    "status": "succeeded",
    "query": "Pflegedienst",
    "filters": {
      "location": "Hamburg",
      "industry": "Gesundheitswesen",
      "country": "de",
      "language": "de",
      "time_range": null,
      "company_websites_only": true,
      "exclude_existing_leads": true,
      "single_decision_maker_only": true,
      "required_data": [
        "phone"
      ],
      "domain_keywords": [
        "pflege"
      ],
      "exclude_keywords": "Stellenangebot",
      "target_audience": "Ambulante Pflegedienste mit 10 bis 50 Mitarbeitenden"
    },
    "leads_requested": 20,
    "leads_found": 14,
    "message": "Es wurden nur 14 von 20 gewünschten Leads gefunden. Mögliche Gründe: strenge Filter (z. B. „Nur Unternehmenswebsites“, Pflicht-Telefon oder Pflicht-Adresse) oder ein kleiner lokaler Markt.",
    "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
    "created_by": null,
    "created_at": "2026-10-17T09:30:12.418Z",
    "updated_at": "2026-10-17T09:41:55.902Z",
    "finished_at": "2026-10-17T09:41:55.902Z",
    "websites_found": 63,
    "not_matching": 31,
    "other_location": 0
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}