Zum Inhalt springen

NumDetect API-Referenz

Alle Endpunkte teilen sich einen API-Schlüssel und ein Guthaben.

EintragWert
Basis-URLhttps://numdetect.com
Auth-HeaderX-API-Key: sk_your_api_key
Antwort-Envelope{ code, msg, data }

Preise werden hier nicht aufgeführt; jedes Produkt wird pro erfolgreicher Prüfung berechnet. Preise ansehen

Authentifizierung

Verwenden Sie einen in den Einstellungen erstellten API-Schlüssel und senden Sie ihn mit jeder Anfrage.

Auth-Header
X-API-Key: sk_your_api_key

Halten Sie Ihren API-Schlüssel geheimRufen Sie diesen Endpunkt immer von Ihrem Server aus auf. Jeder, der den Schlüssel besitzt, kann Ihr Guthaben verbrauchen.

Asynchrone Prüfungen

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Laden Sie eine Datei hoch und erhalten Sie sofort eine Aufgaben-ID; fragen Sie diese ID dann ab, bis sie erfolgreich ist. Die erfolgreiche Antwort enthält result_url, den Download-Link für das Ergebnis. Es gibt nur zwei Aktionen: übermitteln und abfragen. Fragen Sie höchstens einmal alle 30 Sekunden ab.

Parameter

FeldTypBeschreibung
service_typestringProduktcode für die Massenprüfung, eines der unten aufgeführten Produkte.
countrystringISO-3166-1-Code wie US. Erforderlich für Nummernaufgaben: Jede Nummer muss ihre Ländervorwahl enthalten und zu diesem Land gehören (Nummern, die das nicht tun, werden ausgelassen und nicht berechnet); außerdem bestimmt er das Routing. Bei multipart muss er vor file stehen.
filefileEine .txt- oder .csv-Datei mit einer Kennung pro Zeile, bis zu max_file_bytes (standardmäßig 20MB).
Idempotency-KeyheaderOptional, bis zu 128 Zeichen. Wird derselbe Schlüssel erneut gesendet, wird die ursprüngliche Aufgabe zurückgegeben, statt eine zweite zu erstellen.

Produkte in dieser Gruppe

Validierung von Telefonnummern

number_validation_batchTelefon500–500.000 pro Aufgabe

Eine saubere Liste ist der Anfang der nächsten Kampagne. Prüfen Sie Gültigkeits- und Aktivierungssignale, um prüfenswerte Datensätze zu finden, und speisen Sie das strukturierte Ergebnis in Listenbereinigung, CRM-Aktualisierungen und Prüfungen vor der Kontaktaufnahme ein – so beginnt jede Aktion mit klareren Daten.

Aufgabe übermitteln

POST/api/v1/bulk-tasks
Anfrage
curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_validation_batch \
  -F country=US \
  -F file=@numbers.txt
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}
Anfrage
curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}
Ergebnisspalten
FeldBeispiel:Beschreibung
identifier17253100591Die übermittelte Nummer als reine Ziffernfolge mit Ländervorwahl, ohne Pluszeichen oder Leerzeichen (z. B. 17253100591), und der stabile Schlüssel, um Ergebnisse einem Kunden, Lead oder CRM-Datensatz zuzuordnen. Bewahren Sie sie auf, um die Quellliste nachzuverfolgen und Ergebnisse gesammelt zurückzuschreiben; das Feld allein belegt nicht, dass eine Nummer kontaktiert werden kann.
activatedtrueDas von dieser Prüfung zurückgegebene Aktivierungssignal. Nutzen Sie es, um vor der Kontaktaufnahme prüfenswerte Datensätze zu finden, Bereinigungswarteschlangen zu organisieren und die CRM-Segmentierung zu unterstützen; kombinieren Sie es mit Einwilligungs-, Quell- und Interaktionsdaten, statt es als Verbindungs- oder Zustellgarantie zu betrachten. Die Werte sind true oder false.

Nummernaktivität

number_activity_batchTelefon500–500.000 pro Aufgabe

Lassen Sie die nächste Nachverfolgung mit einem Aktivitätssignal beginnen. Finden Sie aktuelle Aktivität über eine vollständige Nummernliste, trennen Sie ruhende Datensätze von prüfenswerten Nummern und nutzen Sie das Ergebnis, um Reaktivierung, Segmentierung und Prioritäten der Kontaktaufnahme zu planen.

Aufgabe übermitteln

POST/api/v1/bulk-tasks
Anfrage
curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_activity_batch \
  -F country=US \
  -F file=@numbers.txt
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}
Anfrage
curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}
Ergebnisspalten
FeldBeispiel:Beschreibung
identifier17253100591Die übermittelte Nummer als reine Ziffernfolge mit Ländervorwahl, ohne Pluszeichen oder Leerzeichen (z. B. 17253100591), mit der das Aktivitätsergebnis in eine Liste, einen Kunden- oder Lead-Datensatz zurückgeschrieben wird. Sie dient nur der Zuordnung und Nachverfolgbarkeit; sie enthält weder Aktivitätszeitpunkt noch Häufigkeit oder Interaktionsdetails.
activatedtrueEin verfügbares Aktivitätssignal, das Teams helfen kann, Prüfungen zu priorisieren, Zielgruppen-Labels zu bilden und den Reaktivierungsrhythmus zu planen. Es ist keine Zählung aktiver Tage, keine Häufigkeit und kein konkreter Beobachtungszeitpunkt; ein fehlendes Signal bedeutet nicht, dass jemand niemals reagieren wird. Die Werte sind true oder false.

High-Value-Nutzer

number_high_value_batchTelefon500–500.000 pro Aufgabe

Finden Sie die Datensätze, die zuerst geprüft werden sollten. Kombinieren Sie hochwertige Gerätemerkmale mit aktueller Netzwerkaktivität, um ein true/false-Signal für potenzielle High-Value-Nutzer zu erhalten – zur Priorisierung von Service, Mitgliedschaften und Kampagnen; es ist ein Prüfsignal, kein Nachweis von Einkommen oder Käufen.

Aufgabe übermitteln

POST/api/v1/bulk-tasks
Anfrage
curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_high_value_batch \
  -F country=US \
  -F file=@numbers.txt
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}
Anfrage
curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}
Ergebnisspalten
FeldBeispiel:Beschreibung
identifier17253100591Die übermittelte Nummer als reine Ziffernfolge mit Ländervorwahl (z. B. 12017200001), mit der das High-Value-Signal dem hochgeladenen Datensatz zugeordnet und durch ein CRM oder eine Prüfwarteschlange verfolgt wird. Sie liefert keine Identität, kein Gerätemodell und keine anderen persönlichen Profildaten.
activatedtrueEin unterstützendes true/false-Signal, abgeleitet aus hochwertigen Gerätemerkmalen und aktueller Netzwerkaktivität. Es kann Mitgliedschafts-, Service- und Marketingteams helfen, Prüfprioritäten festzulegen, bestätigt aber weder Einkommen noch Vermögen, Kaufkraft oder tatsächliche Ausgaben.

E-Commerce-Aktivität

number_ecommerce_batchTelefon500–500.000 pro Aufgabe

Starten Sie die nächste Commerce-Kampagne mit einer fokussierteren Zielgruppe. Finden Sie verfügbare E-Commerce-Aktivitätssignale, bilden Sie Zielgruppen- und Remarketing-Segmente rund um prüfenswerte Datensätze und behalten Sie die Grenze im Blick: Das Ergebnis ist keine Bestellung, keine Kaufabsicht und kein Aktivitätsnachweis auf einer Plattform.

Aufgabe übermitteln

POST/api/v1/bulk-tasks
Anfrage
curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_ecommerce_batch \
  -F country=US \
  -F file=@numbers.txt
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}
Anfrage
curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}
Ergebnisspalten
FeldBeispiel:Beschreibung
identifier17253100591Die übermittelte Nummer als reine Ziffernfolge mit Ländervorwahl, ohne Pluszeichen oder Leerzeichen (z. B. 17253100591), mit der das Commerce-Aktivitätssignal mit Kunden-, Lead- oder Zielgruppendatensätzen verknüpft wird. So können Marketingteams das Ergebnis mit ihren eigenen Einwilligungs-, Browsing-, Bestell- und Mitgliedschaftsdaten zusammenführen; sie enthält keine Bestell- oder Produktinformationen.
activatedtrueEin verfügbares Commerce-Aktivitätssignal, das die Zielgruppenprüfung, die Vorbereitung von Remarketing-Listen und die Planung von Content-Tests fokussieren kann. Es steht nicht für eine Bestellung, einen Transaktionswert, eine Kaufabsicht oder eine bestimmte Plattformaktivität. Die Werte sind true oder false.

Globale Netzbetreiberabfrage

carrier_batchTelefon500–500.000 pro Aufgabe

Machen Sie aus einer Telefonliste routingfähigen Kontext. Ergänzen Sie internationale Datensätze um Netzbetreiber, zugrunde liegenden Netzbetreiber, Leitungstyp, Land, Region und Stadt und nutzen Sie das angereicherte Ergebnis für Routing, regionale Analysen, Segmentierung und CRM-Aktualisierungen.

Aufgabe übermitteln

POST/api/v1/bulk-tasks
Anfrage
curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=carrier_batch \
  -F country=US \
  -F file=@numbers.txt
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}
Anfrage
curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}
Ergebnisspalten
FeldBeispiel:Beschreibung
identifier17253100591Die übermittelte Nummer als reine Ziffernfolge mit Ländervorwahl, ohne Pluszeichen oder Leerzeichen (z. B. 17253100591), und der Zuordnungsschlüssel, um Netzbetreiber-, Leitungs- und geografischen Kontext in die Quellliste zurückzuschreiben. Behalten Sie Ihre eigenen Quellspalten daneben, damit Routing-, Service- und CRM-Teams die Prüfung nachverfolgen, Duplikate behandeln und den richtigen Kunden oder Lead aktualisieren können. Sie identifiziert einen Datensatz; sie belegt nicht, dass die Nummer erreichbar ist.
carrierT-MobileDer kundenseitige Name des Netzbetreibers, sofern erkennbar. Er kann CRM-Datensätze anreichern, das Service-Routing unterstützen, die Prüfung der Nummernzusammensetzung erleichtern und zeigen, wie sich eine Liste auf Netzbetreiber verteilt. Nutzen Sie ihn als operativen Kontext, nicht als Nachweis von Erreichbarkeit oder aktueller Nutzung. Ein leerer Wert bedeutet, dass bei dieser Prüfung kein verwertbarer Name zurückgegeben wurde; er belegt nicht, dass kein Netzbetreiber existiert.
underlying_carrierDer zugrunde liegende Netzbetreiber, sofern erkennbar – hilfreich, um Wiederverkäufer-, virtuelle Betreiber- und portierte Nummernkontexte zu verstehen. Er kann vom kundenseitigen Netzbetreiber abweichen, und diese Abweichung kann Teams helfen, Routing- oder Zuständigkeitsfragen zu untersuchen. Er ist kein Live-Status des Mobilfunknetzes und kein Echtzeit-Verbindungssignal.
number_typeFixed Line or MobileDer zurückgegebene Leitungstyp, etwa mobile, fixed line oder eine andere erkennbare Kategorie. Nutzen Sie ihn, um Mobilfunk- und Festnetzdatensätze zu trennen, das Service-Routing zu planen, die Kanaleignung zu prüfen und ein nützliches CRM-Segment hinzuzufügen. Er ist kein Verbindungsergebnis; behalten Sie einen leeren oder unbekannten Wert zur Prüfung bei, statt ihn als Fehler zu werten.
country_codeUSDer zurückgegebene Länder- oder Gebietscode zum Gruppieren internationaler Listen, zum Anwenden länderspezifischer Routing- und Geschäftsregeln und zum Erstellen regionaler Berichte. Er beschreibt den Nummerierungskontext, nicht das aktuelle Land, den physischen Standort oder die Staatsangehörigkeit einer Person. Grenzüberschreitende Nutzung und virtuelle Nummern sollten mit Ihren eigenen Kundendaten abgeglichen werden.
regionCADer Kontext zu Region, Bundesstaat oder Provinz, sofern verfügbar. Er kann Analysen der Marktabdeckung, regionale Listengruppierung, Servicezuweisung und Betriebsberichte unterstützen. Er stammt aus dem Nummern- und Netzkontext, nicht aus einem Live-Standort, und sollte daher nicht als aktuelles Gebiet des Nutzers gelesen werden; fehlende oder regionsübergreifende Werte erfordern die übliche geschäftliche Prüfung.
cityLOS ANGELESDer Kontext auf Stadtebene, sofern verfügbar. Er kann regionale Berichte verbessern, die Listenzusammensetzung aufzeigen, lokalisierte Abläufe unterstützen und ein fehlendes CRM-Feld füllen. Nummernvergabe, Portierung, virtuelle Nummern und Quellunterschiede können die Genauigkeit auf Stadtebene beeinflussen; wichtige Entscheidungen sollten daher mit vom Nutzer angegebenen oder bestehenden Geschäftsdaten abgeglichen werden.

Guthaben

GET/api/v1/balance

Liest das aktuelle Kontoguthaben in USD-Mikroeinheiten aus. Nur lesend: Es wird kein Prüfdatensatz erstellt und nichts berechnet.

Guthaben

GET/api/v1/balance
Anfrage
curl "https://numdetect.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"
Antwort
{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Parallelität, Zeitlimits und Wiederholungsverhalten

Übermittlungen von Massenaufgaben werden angenommen, bevor die Verarbeitung beginnt. Entscheiden Sie anhand des zurückgegebenen Aufgabenstatus, ob Sie weiter abfragen oder einen Fehler behandeln.

FeldBeschreibung
5 gleichzeitige Anfragen pro BenutzerEine Aufgabenübermittlung belegt einen Anfrage-Slot. Ist für das Konto kein Slot frei, gibt die API 42901 mit Retry-After zurück; warten Sie und übermitteln Sie die Datei erneut.
Abfragen statt wartenDie Übermittlung einer Aufgabe kehrt sofort zurück. Fragen Sie den Status während der Verarbeitung höchstens alle 30 Sekunden ab.
Die Aufgabengröße richtet sich nach dem ProduktJedes Produkt hat eine eigene minimale und maximale Dateigröße, die im Abschnitt zu Aufgaben angezeigt wird.

Fehlercodes

CodeBeschreibung
40000Nicht unterstützter Diensttyp oder widersprüchliche Anfragefelder
40001Ungültiger JSON-Body
40002Ungültige Nummer
40100Fehlender oder ungültiger API-Schlüssel
40200Unzureichendes Guthaben
42200Die übermittelte Aufgabe konnte in ihrer aktuellen Form nicht angenommen werden
42900Ein Nutzungskontingent ist aufgebraucht, oder es gibt zu viele nicht abgeschlossene Bestellungen
42901Alle Anfrage-Slots sind belegt; übermitteln Sie erneut, nachdem eine laufende Anfrage abgeschlossen ist. Die abgelehnte Anfrage wird nicht berechnet und enthält einen Retry-After-Header
50303Der Dienst ist derzeit ausgelastet; es wird nichts berechnet. Warten Sie die Retry-After-Sekunden ab und senden Sie dieselbe Anfrage erneut
50400Die Anfrage wurde nicht innerhalb ihres Timeouts abgeschlossen und wird nicht berechnet; wiederholen Sie sie
50300Wartung des Prüfdienstes