API-Dokumentation API v1

Authentifizierung

Erstellen Sie einen Schlüssel auf der Seite „API-Schlüssel“ und ersetzen Sie dann den Platzhalter unten in Ihrem eigenen Terminal. Die Beispiele sind nur Text; das Kopieren sendet nichts.

# API origin: https://api.numdetect.com
export NUMDETECT_API_KEY='YOUR_API_KEY'

• Senden Sie bei jedem Request Authorization: Bearer <key>. JSON-Requests benötigen außerdem Content-Type: application/json. Cookies, ein CSRF-Header oder ein Origin-Header sind nicht nötig.
• Ein Schlüssel kann Produkte lesen, Einzel- und Massenchecks ausführen, deren Ergebnisse lesen und Ihren Guthabenverlauf lesen. Kontoeinstellungen, Schlüssel und Aufladungen werden nur im angemeldeten Dashboard verwaltet.
• Sie können bis zu 10 Schlüssel erstellen, zum Beispiel einen pro System, und jeden davon sofort löschen.

Bewahren Sie Schlüssel in Ihrer Serverumgebung auf. Legen Sie Schlüssel nicht in URLs, Screenshots, gemeinsamen Protokollen oder eingecheckten Quelldateien ab.

Produkte

Lesen Sie den aktuellen Katalog, bevor Sie Produkt-IDs wählen. Die Response listet jedes angebotene Produkt mit Eingabetyp, Preisen, Mindestmenge für Massenchecks und unterstützten Ländern auf.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/products" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

single und bulk geben an, ob das Produkt derzeit für diese Art von Check verfügbar ist. countries ist ["*"] für alle Länder, eine Liste von Ländercodes oder leer bei E-Mail-Produkten. Preise sind USD micros pro Check.

Einzelcheck

POST /api/v1/checks nimmt eine Telefonnummer oder eine E-Mail-Adresse und eine Liste von Produkt-IDs entgegen. Der Request wartet, bis jedes Produkt geantwortet hat (bis zu etwa 45 Sekunden), und liefert den abgeschlossenen Check.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+12025550147","products":["whatsapp","telegram"]}'

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","products":["apple_email","spotify_email"]}'

Schreiben Sie Telefonnummern mit ihrer +-Landesvorwahl. Für eine Nummer ohne Vorwahl fügen Sie dem Request "country": "GB" (einen ISO-Ländercode) hinzu.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks/$CHECK_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Massencheck

POST /api/v1/bulk-jobs lädt eine Datei als Multipart-Formulardaten hoch. Die Datei wird in eine Liste pro Land aufgeteilt, und jedes Land wird von jedem gewählten Produkt geprüft.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "[email protected]" \
  -F "products=whatsapp,telegram" \
  -F "input_kind=phone" \
  -F "max_cost=50000000" \
  -F "column=0" \
  -F "header=true"

• file: UTF-8-CSV oder reiner Text, bis zu 100 MB und 1.000.000 Zeilen. Andere Spalten bleiben erhalten und werden in der Ergebnisdatei zurückgegeben.
• input_kind ist phone oder email. column ist die 0-basierte Spalte mit den Nummern (Standard 0); header=true überspringt die erste Zeile.
• country (optional) wird für Telefonnummern ohne Landesvorwahl verwendet. Nummern, die mit + oder 00 beginnen, behalten ihr eigenes Land.
• max_cost ist der Höchstbetrag, den Sie zu zahlen bereit sind, in USD micros. Der Auftrag wird abgelehnt, und es wird nichts berechnet, wenn seine Kosten höher wären oder Ihr Guthaben zu niedrig ist.

Massenstatus und Ergebnisse

Lesen Sie den Auftrag, bis status completed, failed oder cancelled ist. Große Listen können eine Weile dauern, fragen Sie daher alle ein bis zwei Minuten ab oder nutzen Sie einen Webhook.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Ergebnisdatei herunterladen

Wenn result_ready true ist, liefert GET /result einen Download-Link, der 10 Minuten gültig ist. Der Link selbst benötigt keinen Schlüssel. Fordern Sie jedes Mal einen neuen Link an, wenn Sie erneut herunterladen möchten.

url=$(curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/result" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" | jq -r .url)
curl --fail --silent --show-error --output result.csv "$url"

result.csv behält jede ursprüngliche Zeile in ihrer ursprünglichen Reihenfolge und ergänzt numdetect_status (valid, duplicate oder invalid), numdetect_country und eine Spalte pro Produkt mit yes, no, unknown, unsupported, failed oder cancelled.

Laufenden Auftrag abbrechen

Länder, die noch nicht geprüft wurden, werden gestoppt, und ihr reservierter Betrag geht zurück auf Ihr Guthaben.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Webhooks

Legen Sie auf der Seite mit den Kontoeinstellungen eine Webhook-URL fest, um benachrichtigt zu werden, wenn ein Massenauftrag abgeschlossen ist. Wir senden pro abgeschlossenem Auftrag einen HTTPS-POST:

{
  "type": "bulk_job.finished",
  "data": {
    "id": "10000000-0000-4000-8000-000000000003",
    "status": "completed",
    "total_rows": 1000,
    "valid_rows": 982,
    "charged": 245500,
    "completed_at": "2026-11-11T08:30:00Z"
  }
}

Jeder Request enthält die Header webhook-id, webhook-timestamp und webhook-signature. Die Signatur ist v1, gefolgt vom Base64-HMAC-SHA256 von "<webhook-id>.<webhook-timestamp>.<body>", berechnet mit Ihrem Signaturgeheimnis (whsec_…, Base64 nach dem Präfix). Vergleichen Sie sie, bevor Sie dem Body vertrauen.

Antworten Sie mit einem beliebigen 2xx-Status. Fehlgeschlagene Zustellungen werden einige Male im Abstand von einigen Minuten wiederholt. Behandeln Sie webhook-id als eindeutig, da eine wiederholte Zustellung doppelt eintreffen kann.

Gebühren und Guthaben

Ein Einzelcheck wird für jedes Produkt mit eindeutiger Antwort zu dessen Preis berechnet. Unbekannte und fehlgeschlagene Antworten sind kostenlos.

Ein Massenauftrag reserviert seine Kosten beim Absenden: für jedes Land und Produkt max(gültige Nummern, Mindestmenge des Produkts) × Mengenpreis. Eine abgeschlossene Liste wird vollständig berechnet, unbekannte Zeilen eingeschlossen. Bei einer Liste, die fehlschlägt oder abgebrochen wird, geht der Betrag zurück auf Ihr Guthaben. Doppelte und ungültige Zeilen sowie Länder, die ein Produkt nicht unterstützt, sind kostenlos.

Beträge sind ganzzahlige USD micros: 1 USD = 1.000.000 micros.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/balance-logs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

POST /checks und POST /bulk-jobs benötigen einen Idempotency-Key-Header (bis zu 128 Zeichen). Verwenden Sie für jeden neuen Request einen neuen Schlüssel. Geht eine Response verloren, senden Sie denselben Request erneut mit demselben Schlüssel: Sie erhalten das erste Ergebnis statt einer zweiten Abbuchung.

Fehler

Fehler verwenden {error: {code, message, request_id}}. Orientieren Sie sich am stabilen code statt an der message und nennen Sie request_id, wenn Sie den Support kontaktieren.

API-Schlüssel erhaltenMassenchecksWebhook-EinstellungenAbrechnung