Referenz

CarrierLookup API-Referenz

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

Eintrag	Wert
Basis-URL	https://carrierlookup.online
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.

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.

Synchrone Prüfungen

POST/api/v1/checkPOST/api/v1/batch-check

Übermitteln Sie eine Telefonnummer oder bis zu 100 in einer Anfrage und lesen Sie das Ergebnis in derselben Antwort. Kein Polling, keine Callbacks. Ein unbestimmtes Ergebnis liefert 422 mit dem Code 42200 und wird nicht berechnet. Eine Mehrfachanfrage behält die Eingabereihenfolge bei, rechnet jede Kennung einzeln ab und hat 300 Sekunden Zeit – wird sie nicht rechtzeitig fertig, schlägt die gesamte Anfrage fehl und alle Abbuchungen werden erstattet.

Parameter

Feld	Typ	Beschreibung
`service_type`	string	Produktcode, eines der unten aufgeführten Produkte.
`identifier`	string	Einzelprüfung: eine Telefonnummer. Der Server normalisiert sie.
`identifiers`	string[]	Mehrfachprüfung: 1 bis 100 Telefonnummern. Die Antwort behält diese Reihenfolge bei.

Produkte in dieser Gruppe

Abfrage des ursprünglichen NetzbetreiberscarrierErmitteln Sie den Netzbetreiber, dem eine Nummer ursprünglich zugeteilt wurde, mit Anschlussart und Standort.Produktseite

Abfrage des ursprünglichen Netzbetreibers

carrierTelefon

Ermitteln Sie den Netzbetreiber, dem eine Nummer ursprünglich zugeteilt wurde, mit Anschlussart und Standort.

Einzelprüfung

POST/api/v1/check

Anfrage

curl -X POST "https://carrierlookup.online/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "identifier": "+17253100591",
    "carrier": "T-Mobile",
    "underlying_carrier": "",
    "number_type": "Fixed Line or Mobile",
    "country_code": "US",
    "region": "NV",
    "city": "LAS VEGAS"
  }
}

Antwortfelder

Feld	Typ	Beschreibung
`carrier`	string	Netzbetreiber, dem die Nummer ursprünglich zugeteilt wurde. Nicht der aktuelle Netzbetreiber nach einer Portierung.
`underlying_carrier`	string	Vom Anbieter gemeldeter zugrunde liegender Netzbetreiber, wenn er vom zugeteilten abweicht; leerer String, wenn der Anbieter keinen liefert.
`number_type`	string	Vom Anbieter gemeldete Anschlussart; leer, wenn nicht verfügbar.
`country_code`	string	ISO-Ländercode des Landes, zu dem die Nummer gehört.
`region`	string	Zuteilungsregion; leer, wenn der Anbieter keine liefert.
`city`	string	Zuteilungsstadt; leer, wenn der Anbieter keine liefert.

Mehrfachprüfung

POST/api/v1/batch-check

Anfrage

curl -X POST "https://carrierlookup.online/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifiers": ["+17253100591", "12345"] }'

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "carrier": "T-Mobile",
        "underlying_carrier": "",
        "number_type": "Fixed Line or Mobile",
        "country_code": "US",
        "region": "NV",
        "city": "LAS VEGAS"
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Antwortfelder

Feld	Typ	Beschreibung
`exists`	boolean	Ob diese Nummer ein Ergebnis geliefert hat. false bedeutet, dass das Format ungültig war, das Ergebnis unbestimmt war oder die Prüfung fehlgeschlagen ist; bei false ist keines der folgenden Felder vorhanden.
`carrier`	string	Netzbetreiber, dem die Nummer ursprünglich zugeteilt wurde. Nicht der aktuelle Netzbetreiber nach einer Portierung.
`underlying_carrier`	string	Vom Anbieter gemeldeter zugrunde liegender Netzbetreiber, wenn er vom zugeteilten abweicht; leerer String, wenn der Anbieter keinen liefert.
`number_type`	string	Vom Anbieter gemeldete Anschlussart; leer, wenn nicht verfügbar.
`country_code`	string	ISO-Ländercode des Landes, zu dem die Nummer gehört.
`region`	string	Zuteilungsregion; leer, wenn der Anbieter keine liefert.
`city`	string	Zuteilungsstadt; leer, wenn der Anbieter keine liefert.

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

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

Globale Netzbetreiber-Abfragecarrier_batchLaden Sie eine ganze Datei mit Nummern hoch: Netzbetreiber, zugrunde liegender Netzbetreiber, Anschlussart, Land, Region und Stadt für jede Nummer – dieselben Felder wie bei der Netzbetreiber-Abfrage in Echtzeit.Produktseite

Globale Netzbetreiber-Abfrage

carrier_batchTelefon1.000–500.000 pro Aufgabe

Laden Sie eine ganze Datei mit Nummern hoch: Netzbetreiber, zugrunde liegender Netzbetreiber, Anschlussart, Land, Region und Stadt für jede Nummer – dieselben Felder wie bei der Netzbetreiber-Abfrage in Echtzeit.

Aufgabe übermitteln

POST/api/v1/bulk-tasks

Anfrage

curl -X POST "https://carrierlookup.online/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": 1015,
    "total": 1015,
    "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://carrierlookup.online/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": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Ergebnisspalten

Feld	Beispiel:	Beschreibung
`identifier`	17253100591	Die übermittelte Nummer als reine Ziffern mit Ländervorwahl, ohne Pluszeichen oder Leerzeichen (z. B. 17253100591).
`carrier`	T-Mobile	Netzbetreiber, dem die Nummer ursprünglich zugeteilt wurde. Nicht der aktuelle Netzbetreiber nach einer Portierung.
`underlying_carrier`		Vom Anbieter gemeldeter zugrunde liegender Netzbetreiber, wenn er vom zugeteilten abweicht; leer, wenn der Anbieter keinen liefert.
`number_type`	Fixed Line or Mobile	Vom Anbieter gemeldete Anschlussart, etwa Fixed Line or Mobile; leer, wenn nicht verfügbar.
`country_code`	US	ISO-Ländercode des Landes, zu dem die Nummer gehört.
`region`	CA	Zuteilungsregion; leer, wenn der Anbieter keine liefert.
`city`	LOS ANGELES	Zuteilungsstadt; leer, wenn der Anbieter keine liefert.

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://carrierlookup.online/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

Netzbetreiber-Abfragen erfolgen synchron. Entscheiden Sie anhand des zurückgegebenen Codes, ob Sie das Ergebnis übernehmen oder es später erneut versuchen.

Feld	Beschreibung
`5 gleichzeitige Anfragen pro Benutzer`	Einzel- und Mehrfachprüfungen teilen sich dieses Limit, und eine Mehrfachanfrage zählt als eine Anfrage, unabhängig davon, wie viele Nummern sie enthält. Zusätzlich läuft pro Konto jeweils nur eine Mehrfachprüfung; eine zweite wird abgelehnt, bis die erste abgeschlossen ist. Wird eines der Limits erreicht, wird sofort code 42901 ohne Berechnung zurückgegeben, zusammen mit einem Retry-After-Header – senden Sie die Anfrage erneut, sobald eine laufende Anfrage abgeschlossen ist.
`60 s Einzelprüfung, 300 s Mehrfachprüfung`	Bei Überschreitung des Zeitlimits wird code 50400 ohne Berechnung zurückgegeben. Eine Mehrfachprüfung mit Zeitüberschreitung schlägt als Ganzes fehl – keine Teilergebnisse, und der volle Betrag wird erstattet.
`Eine Mehrfachprüfung umfasst bis zu 100 Nummern`	Die Ergebnisse behalten Reihenfolge und Länge der Übermittlung bei. Pro Konto läuft jeweils eine Mehrfachprüfung; senden Sie den nächsten Stapel, sobald der vorherige zurückgekommen ist.

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 Nummer konnte derzeit nicht bestimmt werden. Es werden keine Daten zurückgegeben, und die Anfrage wird nicht berechnet
`42900`	Ein Nutzungskontingent ist aufgebraucht, oder es gibt zu viele nicht abgeschlossene Bestellungen
`42901`	Alle fünf Plätze für gleichzeitige Anfragen sind belegt, oder auf diesem Konto läuft bereits eine Mehrfachprüfung; senden Sie erneut, sobald eine laufende Anfrage abgeschlossen ist. Die abgelehnte Anfrage wird nicht berechnet und enthält einen Retry-After-Header
`50303`	Der Dienst ist derzeit ausgelastet; nicht berechnet. Warten Sie die in Retry-After angegebenen Sekunden ab und senden Sie dieselbe Anfrage erneut
`50400`	Die Prüfung wurde nicht innerhalb ihres Zeitlimits abgeschlossen und wird nicht berechnet; wiederholen Sie sie. Eine Zeitüberschreitung beim Stapel lässt den gesamten Stapel fehlschlagen und erstattet den vollen Betrag
`50300`	Wartung des Abfragedienstes