Telefonnummern per Python und Waterfall API finden

Mit Python kannst Du Telefonnummern aus LinkedIn-Profilen finden, indem Du öffentliche Profil-URLs im Format linkedin.com/in/... an die Waterfall Phone Finder API von Datablist sendest. Die API prüft nacheinander geeignete Telefondatenanbieter und gibt gefundene Nummern im internationalen Format inklusive Ländercode zurück.

In diesem Guide setzen wir mit der Requests-Bibliothek eine vollständige Python-Integration um. Anschließend verwenden wir dieselben Ergebnisse, um eine lokale Anrufliste für den Vertrieb zu erstellen, die den Namen, die LinkedIn-URL und den Account Owner jedes Prospects enthält.

📌 Kurzfassung für alle, die wenig Zeit haben

Nutze eine einzige API, um Telefonnummern anhand einer Liste öffentlicher LinkedIn-Profil-URLs zu finden. Erstelle daraus anschließend eine lokale Anrufliste mit dem Namen und Account Owner jedes Prospects. Der Waterfall Phone Finder testet geeignete Anbieter nacheinander und stellt gefundene Nummern für die Prüfung durch Dein Team bereit.

Input: Prospect-Datensätze mit einer öffentlichen LinkedIn-Profil-URL.

Output: Eine lokale Anrufliste mit gefundenen internationalen Telefonnummern, Ländercodes, Namen und Account Ownern.

💡 Du bevorzugst eine No-Code-Lösung? Nutze den Waterfall Phone Finder von Datablist, um Telefonnummern anhand von LinkedIn-Profil-URLs zu finden – ganz ohne Code.

Wenn Du statt Profil-URLs nur Namen hast, folge zuerst dem No-Code-Workflow vom Namen zur Telefonnummer oder finde LinkedIn-Profile aus Namen mit Python.

Python, Requests und Datablist API Key einrichten

Für dieses Python-Beispiel verwende ich das Paket requests. Erstelle einen Projektordner, aktiviere eine virtuelle Umgebung, installiere Requests und lege die Skriptdatei an:

shell

1mkdir waterfall-phone-lookup
2cd waterfall-phone-lookup
3python -m venv .venv
4source .venv/bin/activate
5python -m pip install requests
6touch find_phone_numbers.py
7export DATABLIST_API_KEY="your-api-key"

Erstelle in Deinem Datablist-Konto einen Personal API Key und verwende ihn für DATABLIST_API_KEY. Der Zugriff auf die REST API ist im Growth-Plan enthalten. Auf die Credits für erfolgreiche Suchen gehe ich später in diesem Guide ein.

Telefonnummern mit einer Python-Funktion finden

Das Beispiel nutzt drei editierbare Prospect-Datensätze. Jeder Datensatz enthält eine stabile prospect_id, einen Namen, eine öffentliche LinkedIn-URL und den Account Owner, der für die Prüfung des Ergebnisses zuständig ist:

Florian Poullin unter https://www.linkedin.com/in/florianpoullin/
Satya Nadella unter https://www.linkedin.com/in/satyanadella/
Reid Hoffman unter https://www.linkedin.com/in/reidhoffman/

Nur die stabile ID und die LinkedIn-URL müssen an die API gesendet werden. Name und Account Owner bleiben in Deinem lokalen Quelldatensatz. So bleibt die Lookup-Anfrage kompakt, während alle geschäftlich relevanten Angaben erhalten bleiben, die Dein Team nach der Rückgabe des Ergebnisses benötigt.

Füge dieses vollständige Skript in find_phone_numbers.py ein:

python

1import json
2import os
3import time
4import uuid
5
6import requests
7
8
9def find_phone_numbers(prospects, api_key, settings):
10    """Eine Telefonsuche starten, abwarten und alle Ergebnisse zurückgeben."""
11    tasks_url = "https://api.datablist.com/v1/enrichments/tasks"
12    headers = {"X-API-Key": api_key}
13    inputs = [
14        {
15            "inputId": prospect["prospect_id"],
16            "data": {"profileUrl": prospect["linkedin_url"]},
17        }
18        for prospect in prospects
19    ]
20
21    unique_id = str(uuid.uuid4())
22    print(f"Task uniqueId: {unique_id}", flush=True)
23
24    payload = {
25        "enrichmentId": "waterfall-phone-finder",
26        "uniqueId": unique_id,
27        "settings": settings,
28        "inputs": inputs,
29    }
30    response = requests.post(tasks_url, headers=headers, json=payload)
31    response.raise_for_status()
32    task = response.json()
33    task_id = task["@id"]
34    task_url = f"{tasks_url}/{task_id}"
35
36    while task["status"] not in ("completed", "failed", "stopped"):
37        time.sleep(3)
38        response = requests.get(task_url, headers=headers)
39        response.raise_for_status()
40        task = response.json()
41
42    if task["status"] != "completed":
43        raise RuntimeError(
44            f"Task {task_id} {task['status']}: {task.get('error')}"
45        )
46
47    results = []
48    results_url = f"{task_url}/results"
49    params = {"limit": 100}
50
51    while True:
52        response = requests.get(results_url, headers=headers, params=params)
53        response.raise_for_status()
54        page = response.json()
55        results.extend(page["results"])
56
57        next_cursor = page["nextCursor"]
58        if next_cursor is None:
59            break
60        params["cursor"] = next_cursor
61
62    return results
63
64
65if __name__ == "__main__":
66    api_key = os.environ.get("DATABLIST_API_KEY")
67    if not api_key:
68        raise SystemExit("Lege DATABLIST_API_KEY fest, bevor Du das Skript ausführst.")
69
70    prospects = [
71        {
72            "prospect_id": "prospect-florian-poullin",
73            "name": "Florian Poullin",
74            "linkedin_url": "https://www.linkedin.com/in/florianpoullin/",
75            "account_owner": "Habib",
76        },
77        {
78            "prospect_id": "prospect-satya-nadella",
79            "name": "Satya Nadella",
80            "linkedin_url": "https://www.linkedin.com/in/satyanadella/",
81            "account_owner": "Florian",
82        },
83        {
84            "prospect_id": "prospect-reid-hoffman",
85            "name": "Reid Hoffman",
86            "linkedin_url": "https://www.linkedin.com/in/reidhoffman/",
87            "account_owner": "Habib",
88        },
89    ]
90    settings = {"cacheAge": "30"}
91
92    phone_results = find_phone_numbers(prospects, api_key, settings)
93    print(json.dumps(phone_results, indent=2, ensure_ascii=False))

Führe die Datei so aus:

shell

1python find_phone_numbers.py

Du kannst außerdem das von Datablist gepflegte synchrone Requests-Beispiel herunterladen. Das obige Skript folgt demselben einfachen Ablauf: einen Task absenden, auf dessen Abschluss warten und alle Ergebnisseiten abrufen.

Telefonsuche starten

Die List Comprehension wandelt jeden Prospect aus der Quelldatei in das Input-Format der API um. Deine prospect_id wird zu inputId, während linkedin_url zu data.profileUrl wird. Verwende eine öffentliche Personenprofil-URL mit dem Pfad linkedin.com/in/.... Sales-Navigator-URLs werden von diesem Enrichment nicht unterstützt.

Die Funktion erzeugt eine uniqueId und gibt sie vor dem POST aus. Die Anfrage sendet diesen Wert zusammen mit der Enrichment-ID waterfall-phone-finder, der Cache-Einstellung und den Inputs. Nach erfolgreicher Übermittlung gibt die API HTTP 202 Accepted und eine Task-@id zurück, während die Verarbeitung im Hintergrund weiterläuft.

Die API-Referenz zum Waterfall Phone Finder führt die aktuellen Einstellungen, Input-Felder, Outputs, Credits und Limits auf.

Für einen Prospect hat der Request Body folgende Struktur:

json

{
  "enrichmentId": "waterfall-phone-finder",
  "uniqueId": "generated-uuid",
  "settings": {
    "cacheAge": "30"
  },
  "inputs": [
    {
      "inputId": "prospect-florian-poullin",
      "data": {
        "profileUrl": "https://www.linkedin.com/in/florianpoullin/"
      }
    }
  ]
}

Die öffentliche Profil-URL dient als Input für die Suche. inputId ist der Join Key, der das Ergebnis mit dem Namen und Account Owner im Quelldatensatz verknüpft. Wähle eine ID, die in Deinem eigenen System stabil und innerhalb des Tasks eindeutig ist.

Auf den Hintergrund-Task warten

Der Requests-Client blockiert lokal, während er den Task alle drei Sekunden prüft. Der Datablist-Task läuft dabei weiterhin im Hintergrund. Sobald sein Status completed lautet, ruft die Funktion die Ergebnisse ab. Bei failed oder stopped wird ein Fehler mit der Task-ID ausgelöst, damit Du den Vorgang prüfen kannst.

Alle Ergebnisseiten abrufen

Die Ergebnisanfrage ruft jeweils bis zu 100 Zeilen ab. Weitere Seiten werden geladen, bis nextCursor den Wert null hat. Jedes Ergebnis enthält seine ursprüngliche inputId, sodass Du es unabhängig von der Reihenfolge der Antworten dem richtigen Prospect zuordnen kannst.

So findet die Managed Waterfall eine Telefonnummer

Im Beispiel ist cacheAge auf "30" gesetzt. Datablist prüft zunächst, ob ein geeignetes, höchstens 30 Tage altes Ergebnis vorliegt. Ist das der Fall, kann die API es erneut verwenden. Die Einstellung erlaubt einen Cache Hit, garantiert ihn jedoch nicht.

Bleibt das Profil ungelöst, testet die Managed Waterfall nacheinander geeignete Telefondatenanbieter. Liefert ein Anbieter keine nutzbare Nummer, wird der Datensatz an den nächsten weitergegeben. Eine nutzbare Nummer beendet die Sequenz für diesen Datensatz.

Waterfall-Telefonsuche, die ohne Ergebnis fortgesetzt und beim Fund einer Telefonnummer beendet wird

Vorteile einer Waterfall über Länder und Märkte hinweg

Datablist verlässt sich nicht auf einen einzigen Telefondatenanbieter. Die Anbieter nutzen unterschiedliche Datensätze, und ihre Abdeckung variiert je nach Land und Markt. Hat ein Anbieter keine Telefonnummer, kann ein anderer sie finden. Datablist verwaltet all diese Anbieter über dieselbe API-Integration.

Für ein Vertriebsteam, das eine Anrufliste für mehrere Märkte erstellt, bedeutet das: Weniger Prospects fallen heraus, nur weil ein einzelner Anbieter kein Ergebnis liefert. Dein Python-Code sendet einen Task und verarbeitet ein einheitliches Ergebnisformat. Du musst also nicht für jeden Anbieter eine eigene Integration entwickeln und pflegen.

Setze cacheAge auf "0", wenn Dein Workflow ausdrücklich eine neue Suche anfordern soll. Für dieses Beispiel bleibt der Wert bei "30", damit ein geeignetes Cache-Ergebnis wiederverwendet werden kann.

Das vollständige Ergebnis auslesen

Hier siehst Du ein Ergebnis für Florian Poullin. Die Telefonnummer ist unten maskiert.

json

{
  "inputId": "prospect-florian-poullin",
  "status": "success",
  "outputs": {
    "finderProvider": "wizleads",
    "phoneNumber": "+33 • •• •• •• ••",
    "phoneNumberCountry": "FR"
  },
  "creditsUsed": "500",
  "error": null
}

phoneNumber enthält die internationale Nummer, sofern eine verfügbar ist. Die Vorwahl +33 und phoneNumberCountry: "FR" kennzeichnen eine französische Telefonnummer.

finderProvider zeigt den für dieses Ergebnis gemeldeten Finder. Die Zeile hat 500 Credits verbraucht, und error: null bedeutet, dass die API keinen Fehler auf Zeilenebene zurückgegeben hat.

Geprüfte Anrufliste für den Vertrieb erstellen

Sobald phone_results verfügbar ist, kannst Du eine lokale Liste zur Prüfung durch das Vertriebsteam erstellen. Füge den folgenden Block nach der Ergebnisausgabe in derselben Datei ein. Er verwendet die vorhandenen Ergebnisse und löst keinen zweiten API Call aus:

python

1results_by_id = {
2    result["inputId"]: result
3    for result in phone_results
4}
5
6call_list = []
7
8for prospect in prospects:
9    result = results_by_id.get(prospect["prospect_id"])
10    if not result or result["status"] != "success":
11        continue
12
13    phone_number = result.get("outputs", {}).get("phoneNumber")
14    if not phone_number:
15        continue
16
17    call_list_record = prospect.copy()
18    call_list_record["result"] = result
19    call_list.append(call_list_record)
20
21print(json.dumps(call_list, indent=2, ensure_ascii=False))

Der Ergebnisindex verwendet inputId als Join Key. Dadurch bleibt jedes Ergebnis mit seinem Quelldatensatz verknüpft, ohne von der Position in der Liste abhängig zu sein. Der API Payload enthält die ID und Profil-URL jedes Prospects, während die ursprüngliche Liste prospects den Namen und Account Owner für die Anrufliste aufbewahrt.

Bei Florians Zeile verknüpft prospect-florian-poullin das zurückgegebene Ergebnis mit den ursprünglichen Werten name, linkedin_url und account_owner. Das Team liest die Telefonnummer und den Ländercode FR aus result.outputs aus. Das vollständige API-Objekt mit Status, Credits und Fehler bleibt unter result angehängt.

Die Schleife für die Anrufliste folgt der Reihenfolge von prospects. Sie kopiert jeden aufgenommenen Prospect, bevor sie result anhängt. Dadurch bleibt die ursprüngliche Quellliste für Korrekturen oder einen anderen Follow-up-Kanal verfügbar.

Eine Zeile ohne Ergebnis, mit Fehler oder ohne Telefonnummer bleibt in der unveränderten Liste prospects, wird aber nicht in call_list aufgenommen. Der Code erstellt damit eine lokale Anrufliste für die anschließende Prüfung.

Kosten der Waterfall Phone Finder API berechnen

Jede neue, nicht aus dem Cache stammende Telefonnummer, die von der standardmäßigen Managed Waterfall gefunden wird, kostet 500 Credits. Ein akzeptiertes Cache-Ergebnis kostet 0 Credits, eine Suche ohne Ergebnis ebenfalls. Prüfe creditsUsed in jeder zurückgegebenen Zeile, um die tatsächlichen Kosten zu ermitteln, statt jedes übermittelte Profil pauschal mit 500 zu multiplizieren.

Nutze für Deine Planung diese Formel:

neu gefundene Telefonnummern ohne Cache × 500 Credits

Vierzig neue Nummern kosten 20.000 Credits. Einhundert neue Nummern kosten 50.000 Credits. Beim aktuellen Basispreis für USD-Aufladungen erhältst Du für 20 US-Dollar 20.000 Credits; 500 Credits entsprechen also 0,50 US-Dollar. Das Growth-Abo, das den REST-API-Zugriff enthält, wird separat berechnet. Aktuelle Pläne und Credit-Pakete findest Du auf der Seite Datablist Preise.

Ein Planungsbeispiel: Angenommen, 100 Profile liefern 20 neue Nummern, 5 akzeptierte Nummern aus dem Cache und 75 Suchen ohne Treffer. Abgerechnet werden die 20 neuen Nummern, die Suche verbraucht also 10.000 Credits. Die Anrufliste kann alle 25 gefundenen Nummern enthalten. Trage 20 in den Rechner ein – nicht alle 100 Inputs oder alle 25 gefundenen Nummern. Dieses Beispiel veranschaulicht nur die Kostenberechnung und keine erwartete Erfolgsquote.

Loading pricing…

Häufige Fehler beheben und Tasks wiederherstellen

DATABLIST_API_KEY fehlt: Das Skript wird beendet, bevor es eine Anfrage sendet. Exportiere die Variable und führe die Datei erneut aus.
Die API lehnt den Key ab: raise_for_status() meldet den HTTP-Fehler. Kopiere den Personal API Key erneut und prüfe, ob er im Header X-API-Key gesendet wird.
Die Profil-URL wird nicht unterstützt: Ersetze eine leere, fehlerhafte, zu einem Unternehmen gehörende oder aus Sales Navigator stammende URL durch ein öffentliches Personenprofil mit dem Pfad linkedin.com/in/....
Die Credits reichen nicht aus: Prüfe den Kontostand und die verfügbaren Credits, bevor Du weitere Tasks übermittelst.
Der Task hat den Status failed oder stopped: Prüfe den Fehler, die verfügbaren Ergebnisse und den Credit-Verbrauch, bevor Du entscheidest, was erneut ausgeführt werden muss.
Eine Zeile enthält kein Ergebnis oder einen Fehler: Bewahre den ursprünglichen Prospect für eine Korrektur oder einen anderen Follow-up-Kanal auf. An der Zeile allein lässt sich nicht erkennen, welcher Anbieter, welche Region oder welche Sichtbarkeitsbedingung das Ergebnis verursacht hat.

Falls die POST-Antwort verloren geht, nutze die vor dem Absenden ausgegebene uniqueId. Liste Deine Tasks auf, bevor Du die Anfrage erneut sendest. Ersetze your-api-key in der folgenden Anfrage und suche anschließend den Task, dessen uniqueId mit dem ausgegebenen Wert übereinstimmt:

shell

1curl --get "https://api.datablist.com/v1/enrichments/tasks" \
2  --header "X-API-Key: your-api-key" \
3  --data-urlencode "enrichmentId=waterfall-phone-finder" \
4  --data-urlencode "limit=100"

Befindet sich der Task nicht auf der ersten Seite, folge dem nextCursor aus der Antwort der Task-Liste. Kopiere die @id des passenden Tasks, ersetze unten TASK_ID und prüfe seinen Status oder rufe die vorhandenen Ergebnisse ab:

shell

1curl "https://api.datablist.com/v1/enrichments/tasks/TASK_ID" \
2  --header "X-API-Key: your-api-key"
3
4curl --get "https://api.datablist.com/v1/enrichments/tasks/TASK_ID/results" \
5  --header "X-API-Key: your-api-key" \
6  --data-urlencode "limit=100"

Die Task-API-Dokumentation erklärt Task-Status, die Paginierung von Ergebnissen und das Verhalten bei Unterbrechungen.

Nächste Schritte

Du hast jetzt eine wiederverwendbare Requests-Funktion für öffentliche LinkedIn-Profil-URLs und einen Merge über stabile IDs, der gefundene Telefonnummern für die Prüfung durch den Vertrieb aufbereitet.

Ersetze die editierbaren Beispiele durch eine kleine Auswahl qualifizierter Prospects. Behalte ihre stabilen IDs und Account Owner bei und prüfe jede gefundene Nummer, bevor Du die vorbereitete Liste an den Calling-Prozess Deines Teams übergibst. Starte mit einem kleinen Batch, damit Du die ID-Zuordnung und die zurückgegebenen Felder kontrollieren kannst. Wenn Du nicht blockierende Parallelität benötigst, verwende das gepflegte asynchrone HTTPX-Beispiel.