Referenz
NumDetect API-Referenz
Alle Endpunkte teilen sich einen API-Schlüssel und ein Guthaben.
| Eintrag | Wert |
|---|---|
| Basis-URL | https://numdetect.com |
| Auth-Header | X-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.
X-API-Key: sk_your_api_keyHalten 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
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
| Feld | Typ | Beschreibung |
|---|---|---|
service_type | string | Produktcode für die Massenprüfung, eines der unten aufgeführten Produkte. |
country | string | ISO-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. |
file | file | Eine .txt- oder .csv-Datei mit einer Kennung pro Zeile, bis zu max_file_bytes (standardmäßig 20MB). |
Idempotency-Key | header | Optional, 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_batchEine 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.Produktseite - Nummernaktivität
number_activity_batchLassen 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.Produktseite - High-Value-Nutzer
number_high_value_batchFinden 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.Produktseite - E-Commerce-Aktivität
number_ecommerce_batchStarten 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.Produktseite - Globale Netzbetreiberabfrage
carrier_batchMachen 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.Produktseite
Validierung von Telefonnummern
number_validation_batchTelefon500–500.000 pro AufgabeEine 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-taskscurl -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{
"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}curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"{
"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
| Feld | Beispiel: | Beschreibung |
|---|---|---|
identifier | 17253100591 | Die ü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. |
activated | true | Das 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 AufgabeLassen 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-taskscurl -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{
"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}curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"{
"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
| Feld | Beispiel: | Beschreibung |
|---|---|---|
identifier | 17253100591 | Die ü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. |
activated | true | Ein 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 AufgabeFinden 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-taskscurl -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{
"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}curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"{
"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
| Feld | Beispiel: | Beschreibung |
|---|---|---|
identifier | 17253100591 | Die ü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. |
activated | true | Ein 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 AufgabeStarten 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-taskscurl -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{
"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}curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"{
"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
| Feld | Beispiel: | Beschreibung |
|---|---|---|
identifier | 17253100591 | Die ü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. |
activated | true | Ein 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 AufgabeMachen 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-taskscurl -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{
"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}curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"{
"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
| Feld | Beispiel: | Beschreibung |
|---|---|---|
identifier | 17253100591 | Die ü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. |
carrier | T-Mobile | Der 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_carrier | Der 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_type | Fixed Line or Mobile | Der 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_code | US | Der 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. |
region | CA | Der 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. |
city | LOS ANGELES | Der 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
Liest das aktuelle Kontoguthaben in USD-Mikroeinheiten aus. Nur lesend: Es wird kein Prüfdatensatz erstellt und nichts berechnet.
Guthaben
GET/api/v1/balancecurl "https://numdetect.com/api/v1/balance" \
-H "X-API-Key: sk_your_api_key"{
"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.
| Feld | Beschreibung |
|---|---|
5 gleichzeitige Anfragen pro Benutzer | Eine 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 warten | Die Ü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 Produkt | Jedes Produkt hat eine eigene minimale und maximale Dateigröße, die im Abschnitt zu Aufgaben angezeigt wird. |
Fehlercodes
| Code | Beschreibung |
|---|---|
40000 | Nicht unterstützter Diensttyp oder widersprüchliche Anfragefelder |
40001 | Ungültiger JSON-Body |
40002 | Ungültige Nummer |
40100 | Fehlender oder ungültiger API-Schlüssel |
40200 | Unzureichendes Guthaben |
42200 | Die übermittelte Aufgabe konnte in ihrer aktuellen Form nicht angenommen werden |
42900 | Ein Nutzungskontingent ist aufgebraucht, oder es gibt zu viele nicht abgeschlossene Bestellungen |
42901 | Alle 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 |
50303 | Der Dienst ist derzeit ausgelastet; es wird nichts berechnet. Warten Sie die Retry-After-Sekunden ab und senden Sie dieselbe Anfrage erneut |
50400 | Die Anfrage wurde nicht innerhalb ihres Timeouts abgeschlossen und wird nicht berechnet; wiederholen Sie sie |
50300 | Wartung des Prüfdienstes |