Die Coldleads API

Alles, was die Liste in der App kann, als REST-Schnittstelle: Suchen starten, Leads filtern, Status und Anrufergebnisse zurückschreiben. Für eigene Skripte, dein CRM und KI-Agenten.

Zur API-DokumentationAls MCP-Server
15Endpunkte60Anfragen je MinuteOpenAPIöffentlich

Kurzüberblick

Die REST-API v1 von Coldleads: Suchen, Leads, Listen und Credits per Bearer-Schlüssel — mit denselben Regeln wie die App.

  • Ab Tarif Agency, bis zu 60 Anfragen pro Minute und Schlüssel.
  • Coldleads ist das CRM, das seine Leads selbst findet: Betriebe aus Google Maps, qualifiziert, angerufen und nachgefasst bis zum Termin.
  • API-Aufrufe kosten nichts — Credits nur für neue Betriebe mit Nummer.
  • Derselbe Umfang steht KI-Agenten als MCP-Server zur Verfügung.

Von der Suche zum Status, per Schnittstelle

Vier Schritte, dieselben wie in der App.

1

Suche starten

Branche, Ort, Radius, Zielmenge. Die API kehrt sofort zurück, die Suche läuft Minuten.

POST /searches
2

Stand abfragen

Alle 15 bis 30 Sekunden: gefunden, neu, verbrauchte Credits.

GET /searches/{id}
3

Leads filtern

Ohne Website, ab einer Bewertung, heute fällig — mit Cursor für große Listen.

GET /leads
4

Zurückschreiben

Status, Anrufergebnis, Notiz. Die Liste in der App zeigt dasselbe.

POST /leads/{id}/result

Zwei Aufrufe

Eine Suche starten, dann die Betriebe ohne Website holen. Antworten gekürzt, Betrieb erfunden.

Suche startenPOST /api/v1/searches
curl -X POST https://app.coldleads.net/api/v1/searches \
  -H "Authorization: Bearer cl_live_…" \
  -H "Content-Type: application/json" \
  -d '{"industry": "Friseur", "location": "Köln",
       "radius_km": 20, "target": 300}'

# → 201
{ "id": "7f3c…", "industry": "Friseur", "location": "Köln",
  "status": "laeuft", "found": 0, "new": 0, "credits_spent": 0 }
Leads ohne WebsiteGET /api/v1/leads
curl "https://app.coldleads.net/api/v1/leads?website=ohne&min_rating=4&limit=50" \
  -H "Authorization: Bearer cl_live_…"

# → 200
{ "items": [ { "id": "…", "name": "Salon Beispiel",
    "phone": "+492214710123", "website": null,
    "rating": 4.6, "size_class": "A", "status": "offen" }, … ],
  "next_cursor": "…" }

Das vollständige Schema mit allen Feldern, Filtern und Fehlercodes steht öffentlich unter app.coldleads.net/api/v1/docs, maschinenlesbar als OpenAPI unter /api/v1/openapi.json.

Die Endpunkte

Alles unter /api/v1, alles mit demselben Schlüssel.

EndpunktWas er tut
GET /me, /creditsWorkspace, Guthaben, Kontingent
POST /searchesSuche starten — Branche, Ort, Radius, Zielmenge
GET /searches, /searches/{id}Stand: gefunden, neu, verbrauchte Credits
POST /searches/{id}/pause · resume · stopLaufende Suche steuern
GET /leadsFiltern: Website, Bewertung, PLZ, heute fällig, sortiert, mit Cursor
GET /leads/{id}Ein Betrieb mit Anrufhistorie
POST /leads/{id}/status · result · noteStatus setzen, Anrufergebnis erfassen, Notiz
GET · POST /listsListen lesen und anlegen
POST /lists/{id}/searches · reasonSuche zuordnen, Anlassbegründung setzen

In Entwicklung: ausgehende Webhooks, Zuweisung von Leads an Teammitglieder und E-Mail-Entwürfe. Was wann dazukommt, steht im Changelog.

Dieselben Regeln wie in der App

Die API ist kein zweiter Weg an den Regeln vorbei.

  • Credits: ein Credit je neuem Betrieb mit Telefonnummer. Wiederfunde, Betriebe ohne Nummer und die Aufrufe selbst kosten nichts. Fehlt Guthaben, antwortet POST /searches mit 402.
  • Anlass vor dem Anruf: Status und Anrufergebnis lassen sich erst setzen, wenn die Liste eine Anlassbegründung hat — derselbe Riegel wie in der App, weil im B2B nur mit sachlichem Anlass angerufen werden darf (§ 7 UWG). Mehr unter Ist Kaltakquise erlaubt?
  • Widerspruch: Nummern, die über die Datenherkunftsseite widersprochen haben, liefert die API nicht aus.
  • Fehler: immer als {"fehler": {"code", "text", "hilfe"}}, der Text auf Deutsch, damit ein Skript oder Agent ihn weitergeben kann.

Coldleads bleibt dabei das CRM bis zum Termin. Wer Leads an HubSpot oder Pipedrive übergibt, nutzt heute API oder CSV; ein nativer Sync ist in Entwicklung — siehe Integrationen.

© OpenStreetMap

Den Schlüssel gibt es in der App

Ab Agency: unter „Verwalten → API-Schlüssel“ anlegen, in den Header setzen, erste Suche starten. Die Dokumentation ist öffentlich.

25 Credits für 7 Tage · ohne Kreditkarte. Credits nur für neue Betriebe mit Telefonnummer.

Kostenlos testenAPI-Dokumentation

Häufige Fragen

Hat Coldleads eine API?

Ja, eine REST-API v1 mit OpenAPI-Schema: Suchen starten und steuern, Leads filtern, Status und Anrufergebnisse setzen, Listen verwalten, Guthaben abfragen.

Ab welchem Tarif gibt es die API?

Ab Agency (49 € im Monat). Die Schlüssel legst du in der App unter „Verwalten → API-Schlüssel“ an.

Wie viele Anfragen sind erlaubt?

Bis zu 60 Anfragen pro Minute und Schlüssel. Darüber antwortet die API mit 429 und dem Code `rate_limit`.

Kostet ein API-Aufruf Credits?

Nein. Credits kosten nur neue Betriebe mit Telefonnummer, die eine Suche findet — egal, ob sie über die App, die API oder einen KI-Agenten gestartet wurde.

Gibt es Webhooks?

Ausgehende Webhooks sind in Entwicklung. Bis dahin den Stand einer Suche abfragen; alle 15 bis 30 Sekunden genügt.

Von hier aus weiter

ProduktColdleads als MCP-Server

Dieselben Vorgänge als Werkzeuge für Claude und andere KI-Agenten — ohne eine Zeile Code.

Ansehen IntegrationenIntegrationen

HubSpot, Pipedrive, n8n, Make, Zapier.

IntegrationMit n8n

Suchen und Leads im Workflow.

ChangelogWas neu ist

Jede Ausbaustufe mit Datum.

PreiseTarife

API ab Agency, 49 € im Monat.

Die Liste, die dein Skript anruft.

Suchen, Leads und Status aus der App — als Schnittstelle, mit denselben Regeln und denselben Credits.

Kostenlos testenLive-Demo anfragen