Erste Schritte

Die globale Mobilfunknetz-Infrastruktur basiert auf einem System, das als SS7-Signalisierungsnetzwerk bekannt ist. Dieses Netzwerk ermöglicht den Austausch von Teilnehmerdaten, Call-Routing, SMS-Übertragung und Echtzeit-Updates zum Mobilfunk-Konnektivitätsstatus zwischen Netzbetreibern. Jedes Mobilfunknetz unterhält ein Home Location Register (HLR) - eine zentrale Datenbank, die wesentliche Informationen über seine Teilnehmer speichert.

Die HLR-Lookup-Technologie ermöglicht es Unternehmen, diese Register abzufragen und Live-Konnektivitäts- und Netzwerkdetails für jede Mobilfunknummer abzurufen. Dazu gehören Informationen darüber, ob das Telefon eingeschaltet ist, welchem Netz es derzeit zugeordnet ist, ob es portiert wurde, ob die Nummer gültig oder deaktiviert ist und ob es sich im Roaming befindet.

Die HLR Lookups API bietet nahtlosen Echtzeit-Zugriff auf diese Daten und ermöglicht es Unternehmen, Mobilfunknummern zu verifizieren, das Routing zu optimieren und die Kundenkommunikation zu verbessern. Diese Dokumentation führt Sie durch die Integration von HLR Lookups in Ihre Software und ermöglicht den automatisierten Abruf von Echtzeit-Mobilfunk-Intelligence.

Verwendung der HLR Lookups API

Die Durchführung von HLR-Lookup-Abfragen ist schnell, sicher und unkompliziert. Sobald Sie sich registriert und Ihren API-Schlüssel erhalten haben, können Sie sich authentifizieren und sofortige Lookups mit einfachen HTTP-POST-Anfragen über POST /hlr-lookup durchführen. Alternativ können Sie große Datenmengen verarbeiten, indem Sie schnelle asynchrone API-Anfragen nutzen, bei denen die Ergebnisse per Webhook an Ihren Server zurückgesendet werden, wie im Abschnitt Konzepte erläutert.

Beispielanfrage

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -H "X-Digest-Key: YOUR_API_KEY" \
          -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
          -H "X-Digest-Timestamp: UNIX_TIMESTAMP" \
          -d "@payload.json"

Die Authentifizierung erfolgt über HTTP-Header, und payload.json sollte (mindestens) das folgende JSON-Objekt enthalten:

Beispiel-Payload

{
   "msisdn": "+14156226819"
}

Bei erfolgreicher Ausführung erhalten Sie eine Antwort mit Echtzeit-Konnektivitätsdetails für die angegebene Mobilfunknummer.

Erfolgsantwort application/json

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

Eine vollständige Aufschlüsselung der Anfrage- und Antwort-Attribute sowie Konnektivitätsstatus finden Sie unter POST /hlr-lookup.

Zusätzliche Lookup-Services

Mobile Number Portability (MNP) Lookups

Verwenden Sie MNP-Lookups, um Netzwerkzugehörigkeit und Portierungsdetails zu ermitteln, ohne die Echtzeit-Konnektivität abzufragen. Wenn Sie nur den MCCMNC einer Nummer benötigen, siehe POST /mnp-lookup.

Number Type Detection (NT) Lookups

Ermitteln Sie mit POST /nt-lookup, ob eine Telefonnummer zu einem Festnetz, Mobilfunk, Premium-Dienst, VoIP, Pager oder anderen Nummerierungsplanbereichen gehört.

Software Development Kits (SDKs)

Die HLR Lookups API funktioniert mit jedem REST-Client in jeder Programmiersprache, und wir haben SDKs für PHP, Ruby und NodeJS auf unserem GitHub veröffentlicht, um Ihnen einen schnellen Einstieg zu ermöglichen.

Tools

Um eine nahtlose Entwicklungserfahrung zu gewährleisten, bieten wir eine umfassende Suite von Tools, einschließlich browserbasierter API-Anfrage- und Webhook-Überwachung, IP-Adressen-Whitelisting, robuster Authentifizierungs-Optionen und eines Authentifizierungs-Test-Endpoints.

Kein Entwickler?

HLR-Lookups und Rufnummernportierungs-Abfragen können ohne Programmierung durchgeführt werden. Erfahren Sie mehr über unseren Enterprise-Web-Client und die browserbasierten Reporting-Funktionen.

Authentifizierung

Um Sicherheit und ordnungsgemäße Zugriffskontrolle zu gewährleisten, erfordern die meisten Anfragen an die HLR Lookups API eine Authentifizierung. Endpunkte werden entweder als öffentlich oder geschützt kategorisiert. Beim Zugriff auf einen geschützten Endpunkt muss Ihre Anfrage mit Ihrem API-Schlüssel und Secret über die Methode Digest-Auth oder Basic-Auth authentifiziert werden. Digest-Auth ist die sicherere Option und wird dringend empfohlen. Verwenden Sie den GET /auth-test-Endpunkt, um Ihre Authentifizierungseinrichtung zu überprüfen.

API-Schlüssel und API-Secret

Erhalten Sie Ihren API-Schlüssel und Secret auf der Seite API-Einstellungen. Sie können dort auch Ihre bevorzugte Authentifizierungsmethode konfigurieren und IP-Adressen-Whitelisting für erhöhte Sicherheit aktivieren. Falls Sie vermuten, dass Ihr API-Secret kompromittiert wurde, können Sie jederzeit ein neues generieren.

Basic Auth Digest Auth IP-Whitelist

Standard Basic Authentication ist einfach zu implementieren und wird weitreichend unterstützt. Sie können sich authentifizieren, indem Sie Ihren API-Schlüssel und Secret als user:pass-Paar in der HTTP-Anfrage übergeben.

HTTP Basic Auth

curl 'https://YOUR_API_KEY:YOUR_API_SECRET@www.hlr-lookups.com/api/v2/auth-test'

Dies sendet einen Authorization-Header:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Empfohlen: X-Basic-Header mit SHA256

Für verbesserte Sicherheit können Sie einen SHA256-Hash Ihrer Zugangsdaten senden, anstatt diese direkt als Base64 zu übertragen. Um diese Methode zu verwenden, berechnen Sie den Hash Ihres YOUR_API_KEY:YOUR_API_SECRET-Paars und senden Sie ihn über den X-Basic-Header:

Basic Auth Anfrage

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: BASIC_AUTH_HASH"

Basic Authentication Header

Schlüssel	Typ	Beschreibung
`X-Basic`	string	SHA256-Hash von `YOUR_API_KEY:YOUR_API_SECRET`. Fügen Sie das Doppelpunkt-Symbol (:) in den Hash ein.	erforderlich

Code-Beispiel

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

Digest-Auth ist die empfohlene Methode zur Sicherung des Zugriffs auf geschützte HLR Lookup API-Endpunkte. Jede Anfrage muss die folgenden Header enthalten: X-Digest-Key, X-Digest-Signature und X-Digest-Timestamp, die nachfolgend erläutert werden.

Anfrage-Beispiel

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Anfrage-Header

Schlüssel	Typ	Beschreibung
`X-Digest-Key`	string	Ihr eindeutiger HLR Lookups API-Schlüssel.	erforderlich
`X-Digest-Signature`	string	Eine eindeutige Authentifizierungssignatur (siehe unten).	erforderlich
`X-Digest-Timestamp`	integer	Aktueller Unix-Zeitstempel (siehe auch `GET /time`).	erforderlich

Erstellen der Signatur

Die X-Digest-Signature wird mit einem SHA256-HMAC-Hash erstellt, wobei Ihr API-Secret als gemeinsamer Schlüssel dient.

Die zu hashende Zeichenkette ist wie folgt strukturiert:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Das .-Symbol steht für Zeichenkettenverkettung.

Digest-Signatur-Komponenten

Komponente	Typ	Beschreibung
`ENDPOINT_PATH`	string	Der angeforderte API-Endpunkt, z.B. `/auth-test` in Kleinbuchstaben.
`UNIX_TIMESTAMP`	integer	Aktueller Unix-Zeitstempel (muss innerhalb von 30 Sekunden liegen). Siehe `GET /time`.
`REQUEST_METHOD`	string	Die verwendete HTTP-Methode, z.B. `POST` oder `GET`.
`REQUEST_BODY`	string	Anfrage-Body-Daten. Auf `null` setzen für `GET`-Anfragen.

Code-Beispiele

PHP

NodeJS

Ruby

$path = '/auth-test'
    $timestamp = time();
    $method = 'GET';
    $body = $method == 'GET' ? null : json_encode($params);
    $secret = 'YOUR_API_SECRET';

    $signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

require('crypto');

    let path = '/auth-test'
    let timestamp = Date.now() / 1000 | 0;
    let method = 'GET'
    let body = method === 'GET' ? '' : JSON.stringify(params)
    let secret = 'YOUR_API_SECRET'

    let signature = crypto.createHmac('sha256', secret)
                    .update(path + timestamp + method + body)
                    .digest('hex');

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

Nach oben scrollen

Konzepte

Die Implementierung von HLR-Abfragen in jeder Programmiersprache oder jedem System über unsere HTTP REST API ist unkompliziert und effizient. Mit einem einfachen Integrationsprozess können Sie in Echtzeit Mobilfunknetze abfragen und sofortige Einblicke in die Gültigkeit von Telefonnummern, den Verbindungsstatus und Routing-Details erhalten.

Die Wahl der geeigneten API hängt von Ihrem spezifischen Anwendungsfall ab. Wenn Sie Echtzeit-Abfrageergebnisse für Anwendungen wie VoIP-Telefonie, Betrugserkennung oder SMS-Routing benötigen, ist die synchrone API die beste Wahl. Wenn Ihr Anwendungsfall jedoch die Verarbeitung großer Datenmengen, Massen-Abfragen oder umfangreiche Datenverifizierung umfasst, bietet die asynchrone API optimierte Leistung mit Bandbreiteneffizienz und Batch-Abfragefunktionen.

Konfigurieren Sie die API für eine unserer benutzerdefinierten Routing-Optionen, um Geschwindigkeit, Genauigkeit und Kosteneffizienz zu optimieren. Sie können Abfrageergebnisse auch in Speichern ablegen, um einfache CSV- und JSON-Berichte herunterzuladen sowie erweiterte Analysen über die Weboberfläche durchzuführen.

Synchrone HLR-Abfrage-API

Der POST /hlr-lookup-Endpunkt verarbeitet eine Mobilfunknummer (MSISDN) pro Anfrage und liefert die Ergebnisse sofort im HTTP-Antworttext zurück. Die Ergebnisse werden als JSON formatiert und eignen sich ideal für Echtzeitanwendungen wie Mobilnummernvalidierung, Anruf-Routing und SMS-Nachrichtenzustellung.

Ein synchroner API-Aufruf besteht aus einer direkten HTTP-Anfrage und -Antwort. Ihr System übermittelt eine einzelne MSISDN (Mobilnummer) pro Anfrage und erhält eine sofortige Antwort mit Echtzeit-HLR-Abfrageergebnissen im JSON-Format. Diese API ist für Anwendungsfälle optimiert, die sofortige Verifizierung und Konnektivitätsprüfungen erfordern, wie Betrugserkennung, VoIP-Anruf-Routing und SMS-Gateway-Optimierung.

Asynchrone HLR Lookup API

Der POST /hlr-lookups-Endpunkt ist für Massen- und Hochvolumenverarbeitung konzipiert und ermöglicht die Übermittlung von bis zu 1,000 MSISDNs pro Anfrage. Anstatt Ergebnisse sofort zurückzugeben, verwendet diese API automatisierte Webhooks, um Ergebnisse schrittweise an Ihren Server zu senden. Abfrageergebnisse werden als JSON-Objekte über HTTP-POST-Callbacks zurückgegeben.

Die asynchrone API ist auf Geschwindigkeit, Effizienz und Skalierbarkeit optimiert. Sie eliminiert Netzwerklatenzprobleme, die mit synchronen Aufrufen verbunden sind, und ist daher ideal für Unternehmen, die Abfragen mit hohem Durchsatz benötigen. Ihr System übermittelt bis zu 1,000 MSISDNs pro Anfrage, und unsere Plattform verarbeitet diese parallel und liefert die Ergebnisse über HTTP-Webhooks in Stapeln von bis zu 1,000 Ergebnissen pro Callback an Ihren Server zurück.

SDKs (Software Development Kits)

Unsere Software Development Kits (SDKs) für PHP, NodeJS und Ruby vereinfachen den Integrationsprozess und ermöglichen Ihnen eine effiziente Anbindung an die HLR Lookups API mit minimalem Aufwand.

Diese SDKs bieten vorgefertigte Funktionen, Authentifizierungshandling und strukturierte API-Anfrage-Templates, wodurch die Entwicklungszeit verkürzt und Best Practices gewährleistet werden.

Entdecken Sie unsere vollständige Liste verfügbarer SDKs auf GitHub und starten Sie noch heute mit der Integration.

PHP

NodeJS

Ruby

1   include('HLRLookupClient.class.php');
2
3   $client = new HLRLookupClient(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   );
8
9   $params = array('msisdn' => '+14156226819');
10  $response = $client->post('/hlr-lookup', $params);

Auf GitHub ansehen README.md

1   require('node-hlr-client');
2
3   let response = await client.post('/hlr-lookup', {msisdn: '+491788735000'});
4
5   if (response.status === 200) {
6      // lookup was successful
7      let data = response.data;
8   }

Auf GitHub ansehen README.md

1   require 'ruby_hlr_client/client'
2
3   client = HlrLookupsSDK::Client.new(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   )
8
9   params = { :msisdn => '+14156226819' }
10  response = client.get('/hlr-lookup', params)

Auf GitHub ansehen README.md

Nach oben scrollen

POST/hlr-lookupgeschützt

Führt eine synchrone HLR-Abfrage durch und liefert Echtzeit-Daten zur Mobilfunkkonnektivität und Rufnummernportierung direkt von den Netzbetreibern. Dieser Endpunkt ist ideal für Live-Traffic-Szenarien, bei denen zeitkritische Anwendungen eine sofortige Überprüfung erfordern, ob eine Telefonnummer aktuell erreichbar (verbunden) oder nicht verfügbar (ausgeschaltet) ist. Darüber hinaus hilft er dabei, aktive Nummern von ungültigen, unbekannten oder gefälschten zu unterscheiden.

Für die Massenverarbeitung großer Datenmengen, die keine sofortigen Ergebnisse erfordern, empfiehlt sich der asynchrone POST /hlr-lookups, der für die Hochgeschwindigkeits-Stapelverarbeitung optimiert ist.

Wenn Ihr Hauptaugenmerk auf dem Abruf von Rufnummernportierungsdaten (MCCMNC) liegt und Sie keinen Live-Verbindungsstatus benötigen, bietet der POST /mnp-lookup eine kostengünstige Alternative für Rufnummernportierungsabfragen.

Anfrage Erfolgsantwort Fehlerantwort Status-Referenz

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

Nutzlast

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`msisdn`	string	Die abzufragende Mobiltelefonnummer (MSISDN) im internationalen Format (z. B. +14156226819 oder 0014156226819). Ländercodes müssen enthalten sein.	null	erforderlich
`route`	string(3)	Ein optionaler dreistelliger Bezeichner, der die Route für diese Abfrage festlegt. Setzen Sie diesen auf `null` oder lassen Sie den Parameter weg, um Ihre benutzerdefinierte Routing-Zuordnung anzuwenden oder unser System die beste Route für diese Abfrage automatisch bestimmen zu lassen.	null	optional
`storage`	string	Ein optionaler Speicherbezeichner, der den Report angibt, in dem Ergebnisse für manuelle Überprüfung, Analyse und Berichterstattung gespeichert werden. Das System fügt automatisch einen Zeitstempel mit dem aktuellen Monat hinzu. Wird dieser weggelassen oder auf `null` gesetzt, gruppiert das System die Ergebnisse automatisch nach Monat für Berichtszwecke.	null	optional

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`id`	string(12)	Eine eindeutige Kennung, die dieser Lookup-Anfrage zugewiesen wurde.	false
`msisdn`	string	Die abgefragte Mobiltelefonnummer im internationalen Format (z. B. +14156226819 oder 0014156226819).	false
`connectivity_status`	string	Gibt an, ob der Verbindungsstatus der Nummer erfolgreich abgerufen wurde. Mögliche Werte: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` oder `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Ein fünf- oder sechsstelliger Mobile Country Code (MCC) und Mobile Network Code (MNC), der das aktuell mit der Telefonnummer verbundene Netz identifiziert.	true
`mcc`	string(3)	Ein dreistelliger Mobile Country Code (MCC), der das Land identifiziert, in dem die Telefonnummer registriert ist.	true
`mnc`	string(2\|3)	Ein zwei- oder dreistelliger Mobile Network Code (MNC), der das spezifische Netz identifiziert, zu dem die Telefonnummer gehört.	true
`imsi`	string	Die International Mobile Subscriber Identity (IMSI), eine eindeutige Kennung für die mit dieser Nummer verbundene SIM-Karte. Die Verfügbarkeit hängt von der Netzkonfiguration ab.	true
`msin`	string(10)	Die Mobile Subscription Identification Number (MSIN) in der Datenbank des Mobilfunkbetreibers. Die Verfügbarkeit hängt von der Netzkonfiguration ab.	true
`msc`	string(12)	Die Mobile Switching Center (MSC), die derzeit die Kommunikation dieses Teilnehmers abwickelt. Die Verfügbarkeit hängt von der Netzkonfiguration ab.	true
`original_network_name`	string	Der ursprüngliche (native) Name des Netzbetreibers, der mit dieser Nummer verbunden ist.	true
`original_country_name`	string	Der vollständige Name des Landes, in dem die Mobiltelefonnummer ursprünglich registriert wurde, in englischer Sprache.	true
`original_country_code`	string(2)	Der zweistellige ISO-Ländercode des Landes, in dem die Telefonnummer ursprünglich zugewiesen wurde.	true
`original_country_prefix`	string	Die internationale Vorwahl (Ländervorwahl) des ursprünglichen Landes der Mobiltelefonnummer.	true
`is_ported`	boolean	Gibt an, ob die Mobilnummer von ihrem ursprünglichen Netz zu einem anderen Betreiber portiert wurde.	true
`ported_network_name`	string	Der Name des Netzbetreibers, zu dem die Mobilnummer portiert wurde, falls zutreffend.	true
`ported_country_name`	string	Der Name des Landes, in das die Mobilnummer portiert wurde, falls zutreffend.	true
`ported_country_code`	string(2)	Der zweistellige ISO-Ländercode des Landes, in das die Mobilnummer portiert wurde, falls zutreffend.	true
`ported_country_prefix`	string	Die internationale Vorwahl (Ländervorwahl) des Landes, in das die Mobilnummer portiert wurde, falls zutreffend.	true
`is_roaming`	boolean	Gibt an, ob die Mobilnummer derzeit in einem ausländischen Netz roamt. Die Verfügbarkeit des Roaming-Status hängt vom Mobilfunknetzbetreiber ab.	true
`roaming_network_name`	string	Der Name des Netzes, in dem die Mobilnummer derzeit roamt, falls zutreffend.	true
`roaming_country_name`	string	Der Name des Landes, in dem die Mobilnummer derzeit roamt, falls zutreffend.	true
`roaming_country_code`	string(2)	Der zweistellige ISO-Ländercode des Landes, in dem die Mobilnummer derzeit roamt, falls zutreffend.	true
`roaming_country_prefix`	string	Die internationale Vorwahl (Ländervorwahl) des Landes, in dem die Mobilnummer derzeit roamt, falls zutreffend.	true
`cost`	string	Ein als Zeichenkette dargestellter Dezimalwert, der die Lookup-Kosten in EUR angibt.	true
`timestamp`	string	Ein W3C-formatierter Zeitstempel einschließlich Zeitzone, der angibt, wann der Lookup abgeschlossen wurde.	true
`storage`	string	Der Name des Speichers, in dem die Lookup-Ergebnisse gespeichert wurden. Dies entspricht den Berichtsnamen und CSV-Downloads, die über die Weboberfläche verfügbar sind.	true
`route`	string(3)	Eine dreistellige Kennung, die die für diese Lookup-Anfrage verwendete Routing-Methode angibt.	true
`processing_status`	string	Das Verarbeitungsergebnis des Lookups. Mögliche Werte: `COMPLETED` (erfolgreich), `REJECTED` (Netz nicht erreichbar, keine Gebühr erhoben) oder `FAILED` (Fehler während der Verarbeitung).	false
`error_code`	integer	Ein optionaler interner Fehlercode, der zusätzliche Diagnoseinformationen für den Kundensupport bereitstellt.	true
`error_description`	string	Eine kurze Erklärung des angegebenen Fehlercodes (falls vorhanden) in englischer Klartext-Sprache.	true
`data_source`	string	Die für diese Anfrage verwendete Datenquelle. Mögliche Werte: `LIVE_HLR` (Echtzeit-HLR-Abfrage) oder `MNP_DB` (statische Rufnummernportierungs-Datenbank). Weitere Informationen finden Sie unter Routing-Optionen.	false
`routing_instruction`	string	Eine durch Doppelpunkt getrennte Zeichenkette, die die in der Anfrage verwendete Routing-Anweisung beschreibt. Die erste Komponente ist `STATIC`, wenn Sie eine Route angegeben haben, oder `AUTO` für automatisches Routing; die zweite Komponente ist die Routen-Kennung, und bei automatischen Routing-Anfragen zeigt eine dritte Komponente die Herkunft an, auf der die Routing-Entscheidung basiert (d. h. `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Status	Beschreibung
CONNECTED	Die Nummer ist gültig und das Zielgerät ist derzeit mit dem Mobilfunknetz verbunden. Anrufe, SMS und andere Dienste sollten den Empfänger erfolgreich erreichen.
ABSENT	Die Nummer ist gültig, aber das Zielgerät ist entweder ausgeschaltet oder befindet sich vorübergehend außerhalb der Netzabdeckung. Nachrichten oder Anrufe werden möglicherweise erst zugestellt, wenn das Gerät wieder mit dem Netz verbunden ist.
INVALID_MSISDN	Die Nummer ist ungültig oder derzeit keinem Teilnehmer im Mobilfunknetz zugeordnet. Anrufe und Nachrichten an diese Nummer werden fehlschlagen.
UNDETERMINED	Der Verbindungsstatus der Nummer konnte nicht ermittelt werden. Dies kann auf eine ungültige Nummer, eine SS7-Fehlerantwort oder fehlende Konnektivität mit dem Zielnetzbetreiber zurückzuführen sein. Prüfen Sie den Fehlercode und das Beschreibungsfeld für weitere Diagnoseinformationen.

Nach oben scrollen

POST/hlr-lookupsgeschützt

Startet eine Gruppe asynchroner HLR-Abfragen, die Live-Konnektivitäts- und Portierungsdaten von Mobilfunknetzbetreibern abrufen. Die Ergebnisse werden per Webhook an Ihren Server übermittelt. Diese Methode ist für die Verarbeitung großer Mengen von Nummern optimiert, die keine sofortige Antwort erfordern, wie z.B. Datenbankbereinigung und -verifizierung. Für Echtzeit-Anwendungen wie Call-Routing oder SMS-Zustellung sollten Sie stattdessen den POST /hlr-lookup-Endpunkt verwenden.

Dieser Endpunkt ist ideal für die Massenverarbeitung, wenn das Ziel darin besteht, Telefonnummern zu identifizieren, die derzeit erreichbar (verbunden) oder nicht verfügbar (Telefon ausgeschaltet) sind, während ungültige, nicht zugewiesene oder gefälschte Nummern herausgefiltert werden. Zusätzlich liefert er den aktuellen Portierungsstatus (MCCMNC) zusammen mit den Konnektivitätsdetails.

Bevor Sie diesen Endpunkt verwenden, stellen Sie sicher, dass eine Webhook-URL konfiguriert ist, um Abfrageergebnisse asynchron zu empfangen. Sie können dies in Ihren API-Einstellungen einrichten.

Anfrage Erfolgsantwort Fehlerantwort Webhooks Status-Referenz

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

Nutzlast

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`msisdns`	array	Ein Array von Mobiltelefonnummern (MSISDNs) im internationalen Format (z.B. +14156226819 oder 0014156226819). Sie können bis zu 1000 Nummern pro Anfrage einschließen.	null	erforderlich
`route`	string(3)	Ein optionaler dreistelliger Bezeichner, der die Route für diese Abfrage festlegt. Setzen Sie diesen auf `null` oder lassen Sie den Parameter weg, um Ihre benutzerdefinierte Routing-Zuordnung anzuwenden oder unser System die beste Route für diese Abfrage automatisch bestimmen zu lassen.	null	optional
`storage`	string	Ein optionaler Speicherbezeichner, der den Report angibt, in dem Ergebnisse für manuelle Überprüfung, Analyse und Berichterstattung gespeichert werden. Das System fügt automatisch einen Zeitstempel mit dem aktuellen Monat hinzu. Wird dieser weggelassen oder auf `null` gesetzt, gruppiert das System die Ergebnisse automatisch nach Monat für Berichtszwecke.	null	optional

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`accepted`	array	Eine Liste von Objekten mit eindeutigen Kennungen und MSISDNs, die zur Verarbeitung akzeptiert wurden.	false
`accepted_count`	integer	Die Gesamtzahl der MSISDNs, die erfolgreich zur Verarbeitung akzeptiert wurden.	false
`rejected`	array	Eine Liste von Objekten mit eindeutigen Kennungen und MSISDNs, die für die Verarbeitung abgelehnt wurden, typischerweise aufgrund ungültiger Nummern. Für abgelehnte Einträge fallen keine Gebühren an.	false
`rejected_count`	integer	Die Gesamtzahl der MSISDNs, die aufgrund von Validierungsfehlern abgelehnt wurden.	false
`total_count`	integer	Die Gesamtzahl der akzeptierten und abgelehnten MSISDNs, die zur Verarbeitung eingereicht wurden.	false
`cost`	string	Ein als String dargestellter Dezimalwert, der die Gesamtkosten in EUR für die akzeptierten Abfragen angibt.	false
`storage`	string	Der Name des Speichers, in dem die Abfrageergebnisse gespeichert werden, verwendet für Berichte und CSV-Downloads über die Weboberfläche.	false
`route`	string(3\|4)	Eine drei- oder vierstellige Kennung, die die für diese Abfrageanfrage verwendete Route angibt. Enthält AUTO, wenn nummernbasiertes automatisches Routing angefordert wurde.	false
`webhook_urls`	array	Die in Ihren API-Einstellungen konfigurierten Webhook-URLs. Die Ergebnisse werden hierhin zurückgesendet.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Webhook-Verarbeitung

Nach der Übermittlung beginnt unsere Plattform mit der Verarbeitung der angegebenen Telefonnummern und sendet die Ergebnisse an die zuvor angegebene Webhook-URL auf Ihrem Server. Die Ergebnisse werden als HTTP POST-Anfrage mit einem JSON-Objekt im Anfrage-Body übermittelt.

Authentifizierung

Authentifizieren Sie den Webhook durch Prüfung des X-Signatures HTTP-Headers.

Der X-Signatures-Header enthält eine durch Semikolon getrennte Liste von Signaturen. Jede Signatur in der Liste wird mit einem der in Ihrem Konto konfigurierten API-Secrets generiert. Um den Webhook zu verifizieren, generieren Sie einen SHA-256-Hash mit Ihrem API-Key, Secret und dem rohen HTTP-Body - vergleichen Sie diesen dann mit den Signaturen in der Liste.

Eine Übereinstimmung bestätigt, dass die Anfrage authentisch ist und mit einem von Ihnen kontrollierten Secret signiert wurde.

Code-Beispiel

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

Die Anfrage ist gültig, wenn eine der im Header angegebenen Signaturen einem SHA256-Hash entspricht, der über die verkettete Zeichenfolge aus Ihrem API-Key, Secret und dem HTTP-Body berechnet wurde.

Empfangsbestätigung

Ihr Server muss mit dem HTTP-Statuscode 200 OK antworten, um den erfolgreichen Empfang zu bestätigen. Wenn ein anderer Statuscode zurückgegeben wird, ein Timeout auftritt (10 Sekunden) oder ein anderes Zustellungsproblem entsteht, wiederholt das System den Webhook automatisch nach einer Minute. Wenn die Anfrage weiterhin fehlschlägt, folgen die Wiederholungen einer exponentiellen Backoff-Strategie mit nachfolgenden Versuchen nach 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 Minuten.

Dieser Wiederholungsmechanismus gewährleistet maximale Zuverlässigkeit bei der Zustellung von Lookup-Ergebnissen an Ihre Infrastruktur. Er minimiert das Risiko von Datenverlusten aufgrund vorübergehender Netzwerkprobleme oder Server-Ausfällen.

Webhook-Payload

{
   "type":"HLR",
   "results":[
      {
         "id":"3b4ac4b6ed1b",
         "msisdn":"+905536939460",
         "connectivity_status":"CONNECTED",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "imsi":"28603XXXXXXXXXX",
         "msin":"XXXXXXXXXX",
         "msc":"XXXXXXXXXX",
         "original_network_name":"Turk Telekom (AVEA)",
         "original_country_name":"Turkey",
         "original_country_code":"TR",
         "original_country_prefix":"+90",
         "is_ported":false,
         "ported_network_name":null,
         "ported_country_name":null,
         "ported_country_code":null,
         "ported_country_prefix":null,
         "is_roaming":false,
         "roaming_network_name":null,
         "roaming_country_name":null,
         "roaming_country_code":null,
         "roaming_country_prefix":null,
         "cost":"0.0100",
         "timestamp":"2020-08-13 00:04:38.261+0300",
         "storage":"ASYNC-API-2020-08",
         "route":"IP1",
         "processing_status":"COMPLETED",
         "error_code":null,
         "error_description":null,
         "data_source":"LIVE_HLR",
         "routing_instruction":"STATIC:IP1"
      }
   ]
}

Webhook-Payload-Attribute

Das JSON-Objekt enthält ein Attribut type => HLR sowie ein Attribut results, das eine Liste von Abfrageobjekten enthält, wie unten dokumentiert.

Name	Typ	Beschreibung	Nullable
`id`	string(12)	Eine eindeutige Kennung, die dieser Lookup-Anfrage zugewiesen wurde.	false
`msisdn`	string	Die abgefragte Mobiltelefonnummer im internationalen Format (z. B. +14156226819 oder 0014156226819).	false
`connectivity_status`	string	Gibt an, ob der Verbindungsstatus der Nummer erfolgreich abgerufen wurde. Mögliche Werte: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` oder `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Ein fünf- oder sechsstelliger Mobile Country Code (MCC) und Mobile Network Code (MNC), der das aktuell mit der Telefonnummer verbundene Netz identifiziert.	true
`mcc`	string(3)	Ein dreistelliger Mobile Country Code (MCC), der das Land identifiziert, in dem die Telefonnummer registriert ist.	true
`mnc`	string(2\|3)	Ein zwei- oder dreistelliger Mobile Network Code (MNC), der das spezifische Netz identifiziert, zu dem die Telefonnummer gehört.	true
`imsi`	string	Die International Mobile Subscriber Identity (IMSI), eine eindeutige Kennung für die mit dieser Nummer verbundene SIM-Karte. Die Verfügbarkeit hängt von der Netzkonfiguration ab.	true
`msin`	string(10)	Die Mobile Subscription Identification Number (MSIN) in der Datenbank des Mobilfunkbetreibers. Die Verfügbarkeit hängt von der Netzkonfiguration ab.	true
`msc`	string(12)	Die Mobile Switching Center (MSC), die derzeit die Kommunikation dieses Teilnehmers abwickelt. Die Verfügbarkeit hängt von der Netzkonfiguration ab.	true
`original_network_name`	string	Der ursprüngliche (native) Name des Netzbetreibers, der mit dieser Nummer verbunden ist.	true
`original_country_name`	string	Der vollständige Name des Landes, in dem die Mobiltelefonnummer ursprünglich registriert wurde, in englischer Sprache.	true
`original_country_code`	string(2)	Der zweistellige ISO-Ländercode des Landes, in dem die Telefonnummer ursprünglich zugewiesen wurde.	true
`original_country_prefix`	string	Die internationale Vorwahl (Ländervorwahl) des ursprünglichen Landes der Mobiltelefonnummer.	true
`is_ported`	boolean	Gibt an, ob die Mobilnummer von ihrem ursprünglichen Netz zu einem anderen Betreiber portiert wurde.	true
`ported_network_name`	string	Der Name des Netzbetreibers, zu dem die Mobilnummer portiert wurde, falls zutreffend.	true
`ported_country_name`	string	Der Name des Landes, in das die Mobilnummer portiert wurde, falls zutreffend.	true
`ported_country_code`	string(2)	Der zweistellige ISO-Ländercode des Landes, in das die Mobilnummer portiert wurde, falls zutreffend.	true
`ported_country_prefix`	string	Die internationale Vorwahl (Ländervorwahl) des Landes, in das die Mobilnummer portiert wurde, falls zutreffend.	true
`is_roaming`	boolean	Gibt an, ob die Mobilnummer derzeit in einem ausländischen Netz roamt. Die Verfügbarkeit des Roaming-Status hängt vom Mobilfunknetzbetreiber ab.	true
`roaming_network_name`	string	Der Name des Netzes, in dem die Mobilnummer derzeit roamt, falls zutreffend.	true
`roaming_country_name`	string	Der Name des Landes, in dem die Mobilnummer derzeit roamt, falls zutreffend.	true
`roaming_country_code`	string(2)	Der zweistellige ISO-Ländercode des Landes, in dem die Mobilnummer derzeit roamt, falls zutreffend.	true
`roaming_country_prefix`	string	Die internationale Vorwahl (Ländervorwahl) des Landes, in dem die Mobilnummer derzeit roamt, falls zutreffend.	true
`cost`	string	Ein als Zeichenkette dargestellter Dezimalwert, der die Lookup-Kosten in EUR angibt.	true
`timestamp`	string	Ein W3C-formatierter Zeitstempel einschließlich Zeitzone, der angibt, wann der Lookup abgeschlossen wurde.	true
`storage`	string	Der Name des Speichers, in dem die Lookup-Ergebnisse gespeichert wurden. Dies entspricht den Berichtsnamen und CSV-Downloads, die über die Weboberfläche verfügbar sind.	true
`route`	string(3)	Eine dreistellige Kennung, die die für diese Lookup-Anfrage verwendete Routing-Methode angibt.	true
`processing_status`	string	Das Verarbeitungsergebnis des Lookups. Mögliche Werte: `COMPLETED` (erfolgreich), `REJECTED` (Netz nicht erreichbar, keine Gebühr erhoben) oder `FAILED` (Fehler während der Verarbeitung).	false
`error_code`	integer	Ein optionaler interner Fehlercode, der zusätzliche Diagnoseinformationen für den Kundensupport bereitstellt.	true
`error_description`	string	Eine kurze Erklärung des angegebenen Fehlercodes (falls vorhanden) in englischer Klartext-Sprache.	true
`data_source`	string	Die für diese Anfrage verwendete Datenquelle. Mögliche Werte: `LIVE_HLR` (Echtzeit-HLR-Abfrage) oder `MNP_DB` (statische Rufnummernportierungs-Datenbank). Weitere Informationen finden Sie unter Routing-Optionen.	false
`routing_instruction`	string	Eine durch Doppelpunkt getrennte Zeichenkette, die die in der Anfrage verwendete Routing-Anweisung beschreibt. Die erste Komponente ist `STATIC`, wenn Sie eine Route angegeben haben, oder `AUTO` für automatisches Routing; die zweite Komponente ist die Routen-Kennung, und bei automatischen Routing-Anfragen zeigt eine dritte Komponente die Herkunft an, auf der die Routing-Entscheidung basiert (d. h. `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

Status	Beschreibung
CONNECTED	Die Nummer ist gültig und das Zielgerät ist derzeit mit dem Mobilfunknetz verbunden. Anrufe, SMS und andere Dienste sollten den Empfänger erfolgreich erreichen.
ABSENT	Die Nummer ist gültig, aber das Zielgerät ist entweder ausgeschaltet oder befindet sich vorübergehend außerhalb der Netzabdeckung. Nachrichten oder Anrufe werden möglicherweise erst zugestellt, wenn das Gerät wieder mit dem Netz verbunden ist.
INVALID_MSISDN	Die Nummer ist ungültig oder derzeit keinem Teilnehmer im Mobilfunknetz zugeordnet. Anrufe und Nachrichten an diese Nummer werden fehlschlagen.
UNDETERMINED	Der Verbindungsstatus der Nummer konnte nicht ermittelt werden. Dies kann auf eine ungültige Nummer, eine SS7-Fehlerantwort oder fehlende Konnektivität mit dem Zielnetzbetreiber zurückzuführen sein. Prüfen Sie den Fehlercode und das Beschreibungsfeld für weitere Diagnoseinformationen.

Nach oben scrollen

POST/mnp-lookupgeschützt

Führt eine synchrone MNP-Abfrage durch und liefert Informationen zur Rufnummernportierung und zum Mobilfunknetz. Dieser Endpoint eignet sich, wenn Ihr primäres Ziel darin besteht, den aktuellen MCCMNC einer Mobilfunknummer zu ermitteln und das ursprüngliche sowie aktuelle Netz in Echtzeit zu bestimmen.

Für die Massenverarbeitung großer Datenmengen, die keine sofortigen Ergebnisse erfordern, empfiehlt sich der asynchrone POST /mnp-lookups, der für die Hochgeschwindigkeits-Stapelverarbeitung optimiert ist.

MNP-Abfragen ermitteln zuverlässig Portierungs- und Netzinformationen, geben jedoch keine Auskunft darüber, ob das Ziel-Mobiltelefon derzeit mit einem Netz verbunden und erreichbar ist. Um Live-Konnektivitätsinformationen zu erhalten, verwenden Sie bitte stattdessen den POST /hlr-lookup-Endpoint.

Anfrage Erfolgsantwort Fehlerantwort

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

Nutzlast

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`msisdn`	string	Die abzufragende Mobiltelefonnummer (MSISDN) im internationalen Format (z. B. +14156226819 oder 0014156226819). Ländercodes müssen enthalten sein.	null	erforderlich
`route`	string(3)	Ein optionaler dreistelliger Bezeichner, der die Route für diese Abfrage festlegt. Setzen Sie diesen auf `null` oder lassen Sie den Parameter weg, um Ihre benutzerdefinierte Routing-Zuordnung anzuwenden oder unser System die beste Route für diese Abfrage automatisch bestimmen zu lassen.	null	optional
`storage`	string	Ein optionaler Speicherbezeichner, der den Report angibt, in dem Ergebnisse für manuelle Überprüfung, Analyse und Berichterstattung gespeichert werden. Das System fügt automatisch einen Zeitstempel mit dem aktuellen Monat hinzu. Wird dieser weggelassen oder auf `null` gesetzt, gruppiert das System die Ergebnisse automatisch nach Monat für Berichtszwecke.	null	optional

{
   "id":"e428acb1c0ae",
   "msisdn":"+14156226819",
   "query_status":"OK",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "is_ported":true,
   "original_network_name":"Verizon Wireless:6006 - SVR/2",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1415",
   "ported_network_name":"T-Mobile US:6529 - SVR/2",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "extra":"LRN:4154250000",
   "cost":"0.0050",
   "timestamp":"2020-08-05 21:21:33.490+0300",
   "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
   "route":"PTX",
   "error_code":null
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`id`	string(12)	Eine eindeutige 12-stellige Kennung für diese Abfrage.	false
`msisdn`	string	Die Mobilfunknummer, die in dieser Abfrage geprüft wurde.	false
`query_status`	string	Gibt an, ob die Abfrage der Portierungs- und Netzinformationen erfolgreich war. Mögliche Werte sind `OK` oder `FAILED`.	false
`mccmnc`	string(5\|6)	Ein fünf- oder sechsstelliger MCCMNC (Mobile Country Code und Mobile Network Code) zur Identifikation des Netzes, dem die Mobilfunknummer derzeit zugeordnet ist.	true
`mcc`	string(3)	Ein dreistelliger MCC (Mobile Country Code), der das Land des aktuellen Mobilfunknetzes der Rufnummer repräsentiert.	true
`mnc`	string(2\|3)	Ein zwei- oder dreistelliger MNC (Mobile Network Code) zur Identifikation des aktuellen Netzbetreibers der Mobilfunknummer.	true
`is_ported`	boolean	Gibt an, ob die Rufnummer von ihrem ursprünglichen Netz zu einem neuen Betreiber portiert wurde.	true
`original_network_name`	string	Eine beliebige Zeichenfolge (auf Englisch), die den ursprünglichen Netzbetreiber der geprüften Mobilfunknummer angibt.	true
`original_country_name`	string	Eine beliebige Zeichenfolge (auf Englisch), die das ursprüngliche Land der geprüften Mobilfunknummer angibt.	true
`original_country_code`	string(2)	Ein zweistelliger ISO-Ländercode, der das ursprüngliche Land der geprüften Mobilfunknummer repräsentiert.	true
`original_country_prefix`	string	Die Landesvorwahl des ursprünglichen Landes der geprüften Mobilfunknummer.	true
`ported_network_name`	string	Gibt den Netzbetreiber an, zu dem die geprüfte Mobilfunknummer portiert wurde, sofern zutreffend.	true
`ported_country_name`	string	Gibt das Land an, in das die geprüfte Mobilfunknummer portiert wurde, sofern zutreffend.	true
`ported_country_code`	string(2)	Ein zweistelliger ISO-Ländercode, der das Land repräsentiert, in das die geprüfte Mobilfunknummer portiert wurde, sofern zutreffend.	true
`ported_country_prefix`	string	Die Landesvorwahl des Landes, in das die geprüfte Mobilfunknummer portiert wurde, sofern zutreffend.	true
`extra`	string	Eine beliebige Zeichenfolge mit optionalen zusätzlichen Details zur Rufnummer.	true
`cost`	string	Ein Dezimalwert als Zeichenfolge, der die Kosten in EUR für diese Abfrage angibt.	true
`timestamp`	string	Ein W3C-formatierter Zeitstempel mit Zeitzonenangabe, der den Zeitpunkt des Abfrageabschlusses angibt.	true
`storage`	string	Der Speichername (oder Berichtsname), dem die Abfrageergebnisse hinzugefügt wurden. Dieser wird für CSV-Downloads und Berichte über die Weboberfläche verwendet.	true
`route`	string(3)	Eine dreistellige Kennung, die die für diese Abfrage verwendete Route angibt.	true
`error_code`	integer	Ein optionaler interner Fehlercode zur erweiterten Diagnose durch den Kundensupport.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

POST/mnp-lookupsgeschützt

Initiiert eine Batch-Abfrage asynchroner MNP-Lookups (Rufnummernportierung), ruft den aktuellen MCCMNC ab und ermittelt in Echtzeit das ursprüngliche und aktuelle Netz. Die Ergebnisse werden per Webhook an Ihren Server übermittelt. Diese Methode ist für die Verarbeitung großer Mengen von Nummern optimiert, die keine sofortige Antwort erfordern, wie z.B. Datenbankbereinigung und -verifizierung. Für Echtzeit-Anwendungen wie Call-Routing oder SMS-Zustellung sollten Sie stattdessen den POST /mnp-lookup-Endpunkt verwenden.

MNP-Abfragen ermitteln zuverlässig Portierungs- und Netzinformationen, geben jedoch keine Auskunft darüber, ob das Ziel-Mobiltelefon derzeit mit einem Netz verbunden und erreichbar ist. Um Live-Konnektivitätsinformationen zu erhalten, verwenden Sie bitte stattdessen den POST /hlr-lookups-Endpoint.

Bevor Sie diesen Endpunkt verwenden, stellen Sie sicher, dass eine Webhook-URL konfiguriert ist, um Abfrageergebnisse asynchron zu empfangen. Sie können dies in Ihren API-Einstellungen einrichten.

Anfrage Erfolgsantwort Fehlerantwort Webhooks

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

Nutzlast

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`msisdns`	array	Ein Array von Mobiltelefonnummern (MSISDNs) im internationalen Format (z.B. +14156226819 oder 0014156226819). Sie können bis zu 1000 Nummern pro Anfrage einschließen.	null	erforderlich
`route`	string(3)	Eine optionale dreistellige Kennung zur Angabe der Route für diesen Lookup. Setzen Sie den Wert auf `null` oder lassen Sie diesen Parameter weg, um Ihre benutzerdefinierte Routing-Zuordnung anzuwenden oder unser System automatisch die besten Routen für diese Anfrage ermitteln zu lassen.	null	optional
`storage`	string	Ein optionaler Speicherbezeichner, der den Report angibt, in dem Ergebnisse für manuelle Überprüfung, Analyse und Berichterstattung gespeichert werden. Das System fügt automatisch einen Zeitstempel mit dem aktuellen Monat hinzu. Wird dieser weggelassen oder auf `null` gesetzt, gruppiert das System die Ergebnisse automatisch nach Monat für Berichtszwecke.	null	optional

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`accepted`	array	Eine Liste von Objekten mit eindeutigen Kennungen und MSISDNs, die zur Verarbeitung akzeptiert wurden.	false
`accepted_count`	integer	Die Gesamtzahl der MSISDNs, die erfolgreich zur Verarbeitung akzeptiert wurden.	false
`rejected`	array	Eine Liste von Objekten mit eindeutigen Kennungen und MSISDNs, die für die Verarbeitung abgelehnt wurden, typischerweise aufgrund ungültiger Nummern. Für abgelehnte Einträge fallen keine Gebühren an.	false
`rejected_count`	integer	Die Gesamtzahl der MSISDNs, die aufgrund von Validierungsfehlern abgelehnt wurden.	false
`total_count`	integer	Die Gesamtzahl der akzeptierten und abgelehnten MSISDNs, die zur Verarbeitung eingereicht wurden.	false
`cost`	string	Ein als String dargestellter Dezimalwert, der die Gesamtkosten in EUR für die akzeptierten Abfragen angibt.	false
`storage`	string	Der Name des Speichers, in dem die Abfrageergebnisse gespeichert werden, verwendet für Berichte und CSV-Downloads über die Weboberfläche.	false
`route`	string(3)	Eine dreistellige Kennung, die die für diese Abfrage verwendete Route angibt.	false
`webhook_urls`	array	Die in Ihren API-Einstellungen konfigurierten Webhook-URLs. Die Ergebnisse werden hierhin zurückgesendet.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Webhook-Verarbeitung

Nach der Übermittlung beginnt unsere Plattform mit der Verarbeitung der angegebenen Telefonnummern und sendet die Ergebnisse an die zuvor angegebene Webhook-URL auf Ihrem Server. Die Ergebnisse werden als HTTP POST-Anfrage mit einem JSON-Objekt im Anfrage-Body übermittelt.

Authentifizierung

Authentifizieren Sie den Webhook durch Prüfung des X-Signatures HTTP-Headers.

Der X-Signatures-Header enthält eine durch Semikolon getrennte Liste von Signaturen. Jede Signatur in der Liste wird mit einem der in Ihrem Konto konfigurierten API-Secrets generiert. Um den Webhook zu verifizieren, generieren Sie einen SHA-256-Hash mit Ihrem API-Key, Secret und dem rohen HTTP-Body - vergleichen Sie diesen dann mit den Signaturen in der Liste.

Eine Übereinstimmung bestätigt, dass die Anfrage authentisch ist und mit einem von Ihnen kontrollierten Secret signiert wurde.

Code-Beispiel

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

Die Anfrage ist gültig, wenn eine der im Header angegebenen Signaturen einem SHA256-Hash entspricht, der über die verkettete Zeichenfolge aus Ihrem API-Key, Secret und dem HTTP-Body berechnet wurde.

Empfangsbestätigung

Ihr Server muss mit dem HTTP-Statuscode 200 OK antworten, um den erfolgreichen Empfang zu bestätigen. Wenn ein anderer Statuscode zurückgegeben wird, ein Timeout auftritt (10 Sekunden) oder ein anderes Zustellungsproblem entsteht, wiederholt das System den Webhook automatisch nach einer Minute. Wenn die Anfrage weiterhin fehlschlägt, folgen die Wiederholungen einer exponentiellen Backoff-Strategie mit nachfolgenden Versuchen nach 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 Minuten.

Dieser Wiederholungsmechanismus gewährleistet maximale Zuverlässigkeit bei der Zustellung von Lookup-Ergebnissen an Ihre Infrastruktur. Er minimiert das Risiko von Datenverlusten aufgrund vorübergehender Netzwerkprobleme oder Server-Ausfällen.

Webhook-Payload

{
    "type":"MNP",
    "results":[
        {
           "id":"e428acb1c0ae",
           "msisdn":"+14156226819",
           "query_status":"OK",
           "mccmnc":"310260",
           "mcc":"310",
           "mnc":"260",
           "is_ported":true,
           "original_network_name":"Verizon Wireless:6006 - SVR/2",
           "original_country_name":"United States",
           "original_country_code":"US",
           "original_country_prefix":"+1415",
           "ported_network_name":"T-Mobile US:6529 - SVR/2",
           "ported_country_name":"United States",
           "ported_country_code":"US",
           "ported_country_prefix":"+1",
           "extra":"LRN:4154250000",
           "cost":"0.0050",
           "timestamp":"2020-08-05 21:21:33.490+0300",
           "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
           "route":"PTX",
           "error_code":null
        }
    ]
}

Webhook-Payload-Attribute

Das JSON-Objekt enthält ein Attribut type => MNP sowie ein Attribut results, das eine Liste von Abfrageobjekten enthält, wie unten dokumentiert.

Name	Typ	Beschreibung	Nullable
`id`	string(12)	Eine eindeutige 12-stellige Kennung für diese Abfrage.	false
`msisdn`	string	Die Mobilfunknummer, die in dieser Abfrage geprüft wurde.	false
`query_status`	string	Gibt an, ob die Abfrage der Portierungs- und Netzinformationen erfolgreich war. Mögliche Werte sind `OK` oder `FAILED`.	false
`mccmnc`	string(5\|6)	Ein fünf- oder sechsstelliger MCCMNC (Mobile Country Code und Mobile Network Code) zur Identifikation des Netzes, dem die Mobilfunknummer derzeit zugeordnet ist.	true
`mcc`	string(3)	Ein dreistelliger MCC (Mobile Country Code), der das Land des aktuellen Mobilfunknetzes der Rufnummer repräsentiert.	true
`mnc`	string(2\|3)	Ein zwei- oder dreistelliger MNC (Mobile Network Code) zur Identifikation des aktuellen Netzbetreibers der Mobilfunknummer.	true
`is_ported`	boolean	Gibt an, ob die Rufnummer von ihrem ursprünglichen Netz zu einem neuen Betreiber portiert wurde.	true
`original_network_name`	string	Eine beliebige Zeichenfolge (auf Englisch), die den ursprünglichen Netzbetreiber der geprüften Mobilfunknummer angibt.	true
`original_country_name`	string	Eine beliebige Zeichenfolge (auf Englisch), die das ursprüngliche Land der geprüften Mobilfunknummer angibt.	true
`original_country_code`	string(2)	Ein zweistelliger ISO-Ländercode, der das ursprüngliche Land der geprüften Mobilfunknummer repräsentiert.	true
`original_country_prefix`	string	Die Landesvorwahl des ursprünglichen Landes der geprüften Mobilfunknummer.	true
`ported_network_name`	string	Gibt den Netzbetreiber an, zu dem die geprüfte Mobilfunknummer portiert wurde, sofern zutreffend.	true
`ported_country_name`	string	Gibt das Land an, in das die geprüfte Mobilfunknummer portiert wurde, sofern zutreffend.	true
`ported_country_code`	string(2)	Ein zweistelliger ISO-Ländercode, der das Land repräsentiert, in das die geprüfte Mobilfunknummer portiert wurde, sofern zutreffend.	true
`ported_country_prefix`	string	Die Landesvorwahl des Landes, in das die geprüfte Mobilfunknummer portiert wurde, sofern zutreffend.	true
`extra`	string	Eine beliebige Zeichenfolge mit optionalen zusätzlichen Details zur Rufnummer.	true
`cost`	string	Ein Dezimalwert als Zeichenfolge, der die Kosten in EUR für diese Abfrage angibt.	true
`timestamp`	string	Ein W3C-formatierter Zeitstempel mit Zeitzonenangabe, der den Zeitpunkt des Abfrageabschlusses angibt.	true
`storage`	string	Der Speichername (oder Berichtsname), dem die Abfrageergebnisse hinzugefügt wurden. Dieser wird für CSV-Downloads und Berichte über die Weboberfläche verwendet.	true
`route`	string(3)	Eine dreistellige Kennung, die die für diese Abfrage verwendete Route angibt.	true
`error_code`	integer	Ein optionaler interner Fehlercode zur erweiterten Diagnose durch den Kundensupport.	true

Nach oben scrollen

POST/nt-lookupgeschützt

Führt eine synchrone Nummerntypabfrage (NT) durch. Dieser Endpunkt eignet sich ideal, wenn Ihr primäres Ziel darin besteht, in Echtzeit zu ermitteln, ob die angegebenen Telefonnummern zu Festnetz-, Mobilfunk-, Mehrwertdienst-, VoIP-, Pager- oder anderen Nummerierungsplanbereichen gehören.

NT-Abfragen erkennen zuverlässig den Telefonnummerntyp, geben jedoch keine Auskunft darüber, ob die Zielnummer aktuell mit einem Netz verbunden und erreichbar ist. Um Live-Konnektivitätsinformationen zu erhalten, verwenden Sie bitte den POST /hlr-lookup-Endpunkt.

Wenn Ihr Anwendungsfall präzise Netz- und Portierungsinformationen (MCCMNC) erfordert, jedoch keinen Live-Konnektivitätsstatus, verwenden Sie bitte den POST /mnp-lookup-Endpunkt für Rufnummernportierungsabfragen.

Anfrage Erfolgsantwort Fehlerantwort Typreferenz

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

Nutzlast

{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`number`	string	Eine Telefonnummer im internationalen Format (z. B. +4989702626 oder 004989702626).	null	mandatory
`route`	string(3)	Ein optionaler dreistelliger Bezeichner, der die Route für diese Abfrage festlegt. Setzen Sie diesen Parameter auf `null` oder lassen Sie ihn weg, um Ihre benutzerdefinierte Routing-Zuordnung anzuwenden oder unser System die besten Routen für diese Anfrage automatisch bestimmen zu lassen.	null	optional
`storage`	string	Ein optionaler Speicherbezeichner, der den Report angibt, in dem Ergebnisse für manuelle Überprüfung, Analyse und Berichterstattung gespeichert werden. Das System fügt automatisch einen Zeitstempel mit dem aktuellen Monat hinzu. Wird dieser weggelassen oder auf `null` gesetzt, gruppiert das System die Ergebnisse automatisch nach Monat für Berichtszwecke.	null	optional

{
     "id":"2ed0788379c6",
     "number":"+4989702626",
     "number_type":"LANDLINE",
     "query_status":"OK",
     "is_valid":true,
     "invalid_reason":null,
     "is_possibly_ported":false,
     "is_vanity_number":false,
     "qualifies_for_hlr_lookup":false,
     "mccmnc":null,
     "mcc":null,
     "mnc":null,
     "original_network_name":null,
     "original_country_name":"Germany",
     "original_country_code":"DE",
     "regions":[
        "Munich"
     ],
     "timezones":[
        "Europe/Berlin"
     ],
     "info_text":"This is a landline number.",
     "cost":"0.0050",
     "timestamp":"2015-12-04 10:36:41.866283+00",
     "storage":"SYNC-API-NT-2015-12",
     "route":"LC1"
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`id`	string(12)	Eine eindeutige Kennung, die dieser Lookup-Anfrage zugewiesen wurde.	false
`number`	string	Die Telefonnummer, die bei dieser Lookup-Anfrage ausgewertet wurde.	false
`number_type`	string	Der erkannte Nummerntyp. Mögliche Werte sind: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Gibt an, ob die Nummerntyp-Informationen erfolgreich abgerufen wurden. Gibt `OK` bei Erfolg zurück oder `FAILED`, wenn der Lookup fehlgeschlagen ist.	false
`is_valid`	boolean	Gibt an, ob die Telefonnummer syntaktisch gültig ist.	true
`invalid_reason`	string	Eine Klartextnachricht auf Englisch, die angibt, warum die Telefonnummer als ungültig betrachtet wird (z. B. "too short" oder "invalid prefix"), oder `null`, wenn die Nummer gültig ist.	true
`is_possibly_ported`	boolean	Gibt an, ob die Telefonnummer möglicherweise vom ursprünglichen Betreiber zu einem anderen Anbieter portiert wurde. Für definitive Portierungsinformationen verwenden Sie MNP-Lookups.	true
`is_vanity_number`	boolean	Gibt an, ob die Telefonnummer eine Vanity-Nummer ist, d. h. alphabetische Zeichen enthält.	true
`qualifies_for_hlr_lookup`	boolean	Gibt an, ob die Telefonnummer für zusätzliche Abfragen über HLR-Lookups geeignet ist.	true
`mccmnc`	string(5\|6)	Eine fünf- oder sechsstellige Zeichenfolge, die das MCCMNC-Tupel (Mobile Country Code und Mobile Network Code) darstellt, das das ursprüngliche Netz der Mobilfunknummer identifiziert.	true
`mcc`	string(3)	Eine dreistellige Zeichenfolge, die den MCC (Mobile Country Code) darstellt, der das Land des ursprünglichen Mobilfunknetzes der Telefonnummer identifiziert.	true
`mnc`	string(2\|3)	Eine zwei- oder dreistellige Zeichenfolge, die den MNC (Mobile Network Code) darstellt, der den ursprünglichen Mobilfunknetzbetreiber der Telefonnummer identifiziert.	true
`original_network_name`	string	Eine beliebige englische Klartextzeichenfolge, die den Namen des ursprünglichen Netzbetreibers der geprüften Mobilfunknummer angibt.	true
`original_country_name`	string	Eine beliebige englische Klartextzeichenfolge, die das ursprüngliche Land der geprüften Mobilfunknummer angibt.	true
`original_country_code`	string(2)	Ein zweistelliger ISO-Ländercode, der das ursprüngliche Land der geprüften Mobilfunknummer angibt.	true
`regions`	array	Eine Liste lesbarer englischer Zeichenfolgen, die die geografische(n) Region(en) angeben, die mit dieser Telefonnummer verbunden sind.	true
`timezones`	array	Eine Liste von Zeitzonen (im Olson-Format), die mit dieser Telefonnummer verbunden sind.	true
`info_text`	string	Eine beliebige Zeichenfolge, die zusätzliche Informationen über die Telefonnummer enthalten kann.	true
`cost`	string	Ein als Zeichenfolge dargestellter Dezimalwert, der die Kosten (in EUR) für diesen Lookup angibt.	true
`timestamp`	string	Ein W3C-formatierter Zeitstempel (einschließlich Zeitzone), der angibt, wann der Lookup abgeschlossen wurde.	true
`storage`	string	Gibt den Speichernamen an, in dem die Lookup-Ergebnisse gespeichert wurden. Dies entspricht dem Berichtsnamen, der für CSV-Downloads und Analysen über die Weboberfläche verwendet wird.	true
`route`	string(3)	Eine dreistellige Kennung, die die für diese Abfrage verwendete Route angibt.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Typ	Beschreibung
LANDLINE	Festnetznummer.
MOBILE	Mobilfunknummer. Qualifiziert für HLR-Abfragen zur Ermittlung zusätzlicher Informationen zu Verbindungsstatus, Netz, Portierung und Roaming.
MOBILE_OR_LANDLINE	Festnetz- oder Mobilfunknummer. Möglicherweise für HLR-Abfrage geeignet.
TOLL_FREE	Gebührenfreie Rufnummer.
PREMIUM_RATE	Mehrwertdiensterufnummer mit zusätzlichen Gebühren.
SHARED_COST	Geteilte-Kosten-Rufnummer. Typischerweise günstiger als Mehrwertdiensterufnummern.
VOIP	Voice-over-IP-Rufnummer. Umfasst TSoIP-Rufnummern (Telephony Service over IP).
PAGER	Pager-Rufnummer. Typischerweise ohne Sprachfunktion.
UAN	Universelle Zugangsrufnummer (Firmennummer). Kann zu bestimmten Niederlassungen weitergeleitet werden, ermöglicht jedoch eine einheitliche Nummer für das Unternehmen.
VOICEMAIL	Voicemail-Rufnummer.
UNKNOWN	Nummerntyp konnte nicht ermittelt werden.

Nach oben scrollen

POST/nt-lookups geschützt

Dieser Endpunkt führt eine Reihe asynchroner Nummerntyp-Abfragen durch, deren Ergebnisse per Webhook an Ihren Server zurückgesendet werden. Er eignet sich, wenn Ihr primäres Ziel darin besteht festzustellen, ob die angegebenen Telefonnummern zu Festnetz-, Mobilfunk-, Premium-Rate-, VoIP-, Pager- oder anderen Nummernplanbereichen gehören. Optimiert für die schnelle Verarbeitung großer Nummernmengen ist dieser Endpunkt ideal für Massenvorgänge (z.B. Datenbank-Bereinigung). Für Live-Traffic und zeitkritische Anwendungsfälle verwenden Sie bitte stattdessen den POST /nt-lookup-Endpunkt.

Sie müssen in Ihren API-Einstellungen eine Webhook-URL angeben, um diesen Endpunkt aufrufen zu können.

Anfrage Erfolgsantwort Fehlerantwort Webhooks Typreferenz

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

Nutzlast

{
   "numbers":["+14156226819","+4989702626"],
   "route":null,
   "storage":null
}

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`numbers`	array	Ein Array von Telefonnummern im internationalen Format (z.B. +14156226819 oder 004989702626). Pro Anfrage können maximal 1000 Nummern übermittelt werden.	null	erforderlich
`route`	string(3)	Ein optionales dreistelliges Kennzeichen zur Angabe der Route für diese Abfrage. Setzen Sie diesen Parameter auf `null` oder lassen Sie ihn weg, um Ihre benutzerdefinierte Routing-Zuordnung anzuwenden oder unser System die beste Route für diese Anfrage automatisch bestimmen zu lassen.	null	optional
`storage`	string	Ein optionaler Speicherbezeichner, der den Report angibt, in dem Ergebnisse für manuelle Überprüfung, Analyse und Berichterstattung gespeichert werden. Das System fügt automatisch einen Zeitstempel mit dem aktuellen Monat hinzu. Wird dieser weggelassen oder auf `null` gesetzt, gruppiert das System die Ergebnisse automatisch nach Monat für Berichtszwecke.	null	optional

{
   "accepted":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "number":"+31"
      }
   ],
   "rejected_count":2,
   "total_count":3,
   "cost":0.005,
   "storage":"ASYNC-API-NT-2020-08",
   "route":"LC1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`accepted`	array	Ein Array von Objekten, die jeweils eine eindeutige Kennung und eine zur Verarbeitung akzeptierte Telefonnummer enthalten.	false
`accepted_count`	integer	Die Gesamtanzahl der zur Verarbeitung akzeptierten Telefonnummern.	false
`rejected`	array	Ein Array von Objekten, die jeweils eine eindeutige Kennung und eine zur Verarbeitung abgelehnte Telefonnummer enthalten. In der Regel sind diese Nummern ungültig und es erfolgt keine Berechnung.	false
`rejected_count`	integer	Die Gesamtanzahl der zur Verarbeitung abgelehnten Telefonnummern.	false
`total_count`	integer	Die Gesamtanzahl der akzeptierten und abgelehnten Telefonnummern, die zur Verarbeitung übermittelt wurden.	false
`cost`	string	Eine Zeichenfolge, die einen Dezimalwert darstellt und die Kosten in EUR für diese Abfragen angibt.	false
`storage`	string	Der Name des Speichers (Reports), in dem die Abfrageergebnisse gespeichert wurden. Dieser Name wird für CSV-Downloads und Analysen über die Weboberfläche verwendet.	false
`route`	string(3)	Ein dreistelliges Kennzeichen, das die für diese Abfrage verwendete Route angibt.	false
`webhook_urls`	array	Die in Ihren API-Einstellungen konfigurierten Webhook-URLs. Die Ergebnisse werden hierhin zurückgesendet.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Webhook-Verarbeitung

Nach der Übermittlung beginnt unsere Plattform mit der Verarbeitung der angegebenen Telefonnummern und sendet die Ergebnisse an die zuvor angegebene Webhook-URL auf Ihrem Server. Die Ergebnisse werden als HTTP POST-Anfrage mit einem JSON-Objekt im Anfrage-Body übermittelt.

Authentifizierung

Authentifizieren Sie den Webhook durch Prüfung des X-Signatures HTTP-Headers.

Der X-Signatures-Header enthält eine durch Semikolon getrennte Liste von Signaturen. Jede Signatur in der Liste wird mit einem der in Ihrem Konto konfigurierten API-Secrets generiert. Um den Webhook zu verifizieren, generieren Sie einen SHA-256-Hash mit Ihrem API-Key, Secret und dem rohen HTTP-Body - vergleichen Sie diesen dann mit den Signaturen in der Liste.

Eine Übereinstimmung bestätigt, dass die Anfrage authentisch ist und mit einem von Ihnen kontrollierten Secret signiert wurde.

Code-Beispiel

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

Die Anfrage ist gültig, wenn eine der im Header angegebenen Signaturen einem SHA256-Hash entspricht, der über die verkettete Zeichenfolge aus Ihrem API-Key, Secret und dem HTTP-Body berechnet wurde.

Empfangsbestätigung

Ihr Server muss mit dem HTTP-Statuscode 200 OK antworten, um den erfolgreichen Empfang zu bestätigen. Wenn ein anderer Statuscode zurückgegeben wird, ein Timeout auftritt (10 Sekunden) oder ein anderes Zustellungsproblem entsteht, wiederholt das System den Webhook automatisch nach einer Minute. Wenn die Anfrage weiterhin fehlschlägt, folgen die Wiederholungen einer exponentiellen Backoff-Strategie mit nachfolgenden Versuchen nach 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 Minuten.

Dieser Wiederholungsmechanismus gewährleistet maximale Zuverlässigkeit bei der Zustellung von Lookup-Ergebnissen an Ihre Infrastruktur. Er minimiert das Risiko von Datenverlusten aufgrund vorübergehender Netzwerkprobleme oder Server-Ausfällen.

Webhook-Payload

{
   "type":"NT",
   "results":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460",
         "numbertype":"MOBILE",
         "state":"COMPLETED",
         "isvalid":"Yes",
         "invalidreason":null,
         "ispossiblyported":"Yes",
         "isvanitynumber":"No",
         "qualifiesforhlrlookup":"Yes",
         "originalcarrier":"Turk Telekom (AVEA)",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "countrycode":"TR",
         "regions":[
            "Turkey"
         ],
         "timezones":[
            "Europe\/Istanbul"
         ],
         "infotext":"This number qualifies for HLR lookups. Determine if this subscriber number is connected, absent or invalid by running an HLR lookup. This is a mobile number and might be in roaming state. Run an HLR lookup to obtain roaming information (if available). This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup.",
         "usercharge":"0.0050",
         "inserttime":"2020-08-13 01:57:15.897+0300",
         "storage":"ASYNC-API-NT-2020-08",
         "route":"LC1",
         "interface":"Async API"
      }
   ]
}

Webhook-Payload-Attribute

Das JSON-Objekt enthält ein Attribut type => NT sowie ein Attribut results, das eine Liste von Abfrageobjekten enthält, wie unten dokumentiert.

Name	Typ	Beschreibung	Nullable
`id`	string(12)	Eine eindeutige Kennung, die dieser Lookup-Anfrage zugewiesen wurde.	false
`number`	string	Die Telefonnummer, die bei dieser Lookup-Anfrage ausgewertet wurde.	false
`number_type`	string	Der erkannte Nummerntyp. Mögliche Werte sind: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Gibt an, ob die Nummerntyp-Informationen erfolgreich abgerufen wurden. Gibt `OK` bei Erfolg zurück oder `FAILED`, wenn der Lookup fehlgeschlagen ist.	false
`is_valid`	boolean	Gibt an, ob die Telefonnummer syntaktisch gültig ist.	true
`invalid_reason`	string	Eine Klartextnachricht auf Englisch, die angibt, warum die Telefonnummer als ungültig betrachtet wird (z. B. "too short" oder "invalid prefix"), oder `null`, wenn die Nummer gültig ist.	true
`is_possibly_ported`	boolean	Gibt an, ob die Telefonnummer möglicherweise vom ursprünglichen Betreiber zu einem anderen Anbieter portiert wurde. Für definitive Portierungsinformationen verwenden Sie MNP-Lookups.	true
`is_vanity_number`	boolean	Gibt an, ob die Telefonnummer eine Vanity-Nummer ist, d. h. alphabetische Zeichen enthält.	true
`qualifies_for_hlr_lookup`	boolean	Gibt an, ob die Telefonnummer für zusätzliche Abfragen über HLR-Lookups geeignet ist.	true
`mccmnc`	string(5\|6)	Eine fünf- oder sechsstellige Zeichenfolge, die das MCCMNC-Tupel (Mobile Country Code und Mobile Network Code) darstellt, das das ursprüngliche Netz der Mobilfunknummer identifiziert.	true
`mcc`	string(3)	Eine dreistellige Zeichenfolge, die den MCC (Mobile Country Code) darstellt, der das Land des ursprünglichen Mobilfunknetzes der Telefonnummer identifiziert.	true
`mnc`	string(2\|3)	Eine zwei- oder dreistellige Zeichenfolge, die den MNC (Mobile Network Code) darstellt, der den ursprünglichen Mobilfunknetzbetreiber der Telefonnummer identifiziert.	true
`original_network_name`	string	Eine beliebige englische Klartextzeichenfolge, die den Namen des ursprünglichen Netzbetreibers der geprüften Mobilfunknummer angibt.	true
`original_country_name`	string	Eine beliebige englische Klartextzeichenfolge, die das ursprüngliche Land der geprüften Mobilfunknummer angibt.	true
`original_country_code`	string(2)	Ein zweistelliger ISO-Ländercode, der das ursprüngliche Land der geprüften Mobilfunknummer angibt.	true
`regions`	array	Eine Liste lesbarer englischer Zeichenfolgen, die die geografische(n) Region(en) angeben, die mit dieser Telefonnummer verbunden sind.	true
`timezones`	array	Eine Liste von Zeitzonen (im Olson-Format), die mit dieser Telefonnummer verbunden sind.	true
`info_text`	string	Eine beliebige Zeichenfolge, die zusätzliche Informationen über die Telefonnummer enthalten kann.	true
`cost`	string	Ein als Zeichenfolge dargestellter Dezimalwert, der die Kosten (in EUR) für diesen Lookup angibt.	true
`timestamp`	string	Ein W3C-formatierter Zeitstempel (einschließlich Zeitzone), der angibt, wann der Lookup abgeschlossen wurde.	true
`storage`	string	Gibt den Speichernamen an, in dem die Lookup-Ergebnisse gespeichert wurden. Dies entspricht dem Berichtsnamen, der für CSV-Downloads und Analysen über die Weboberfläche verwendet wird.	true
`route`	string(3)	Eine dreistellige Kennung, die die für diese Abfrage verwendete Route angibt.	true

Typ	Beschreibung
LANDLINE	Festnetznummer.
MOBILE	Mobilfunknummer. Qualifiziert für HLR-Abfragen zur Ermittlung zusätzlicher Informationen zu Verbindungsstatus, Netz, Portierung und Roaming.
MOBILE_OR_LANDLINE	Festnetz- oder Mobilfunknummer. Möglicherweise für HLR-Abfrage geeignet.
TOLL_FREE	Gebührenfreie Rufnummer.
PREMIUM_RATE	Mehrwertdiensterufnummer mit zusätzlichen Gebühren.
SHARED_COST	Geteilte-Kosten-Rufnummer. Typischerweise günstiger als Mehrwertdiensterufnummern.
VOIP	Voice-over-IP-Rufnummer. Umfasst TSoIP-Rufnummern (Telephony Service over IP).
PAGER	Pager-Rufnummer. Typischerweise ohne Sprachfunktion.
UAN	Universelle Zugangsrufnummer (Firmennummer). Kann zu bestimmten Niederlassungen weitergeleitet werden, ermöglicht jedoch eine einheitliche Nummer für das Unternehmen.
VOICEMAIL	Voicemail-Rufnummer.
UNKNOWN	Nummerntyp konnte nicht ermittelt werden.

Nach oben scrollen

GET/routegeschützt

Ruft die Route ab, die automatisch ausgewählt wird, wenn Sie eine HLR-Abfrage ohne Angabe des Parameters route durchführen.

Die automatische Routenauswahl basiert auf der Routing-Zuordnung, die über den Endpunkt GET /hlr-coverage abrufbar ist und primär aus GET /routing-map abgeleitet wird. Sie können Ihre Routing-Zuordnung anpassen und benutzerdefinierte Regeln in Ihren Kontoeinstellungen definieren.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`msisdn`	string	Die MSISDN, für die die automatisch ausgewählten Routing-Informationen abgerufen werden sollen.	null	erforderlich

{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`route`	string	Die empfohlene Route.	false
`confidence_level`	string	Das Konfidenzniveau, mit dem diese Route ausgewählt wurde, d.h. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	Der auf dem Nummerierungsplan basierende MCCMNC für diese Nummer.	false
`origin`	string	Die Herkunft, auf der die Routing-Entscheidung basiert, d. h. `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/routesgeschützt

Dieser Endpunkt gibt eine Liste der verfügbaren HLR-, MNP- und NT-Routen zurück. Jede Route wird mit ihren Funktionen und Einschränkungen auf der Seite Routing-Details erläutert.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/routes'

{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`routes`	object	Ein Objekt mit Routen, gruppiert nach Routentyp.	false
`HLR\|MNP\|NT`	string[]	Enthält eine Liste von Routen-Identifikatoren.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/routing-mapgeschützt

Ruft die automatisierte Routing-Konfiguration ab, die derzeit für HLR-Abfragen in Ihrem Konto angewendet wird. Diese Standardkonfiguration wird verwendet, wenn Sie HLR-Abfragen ohne Angabe eines route-Parameters übermitteln. Sie können Ihre Routing-Map anpassen und benutzerdefinierte Regeln in Ihren Kontoeinstellungen erstellen.

Die Konfigurationshierarchie erstreckt sich von Länderregeln über MCCMNC-Regeln bis hin zu individuellen Telefonnummern-Präfix-Zuordnungen. In der Praxis bedeutet dies, dass individuelle Telefonnummern-Präfix-Zuordnungen Vorrang vor widersprüchlichen MCCMNC-Zuweisungen haben, die wiederum Länderregeln überschreiben. Bitte beachten Sie, dass MNP-Fallback alle widersprüchlichen benutzerdefinierten Regeln überschreibt, solange es aktiviert ist.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/routing-map'

{
   "routing":{
      "map":{
         "defaultRoute":"V11",
         "mnpFallback":true,
         "mccmncs":[
            {
               "mccmnc":20201,
               "countrycode":"GR",
               "route":"E10",
               "mno":"Cosmote",
               "confidence":"HIGH",
               "origin":"SCORE"
            }
         ],
         "prefixes":[
            {
               "countrycode":"DE",
               "cns":"+4917821",
               "route":"DV8",
               "mccmnc":"26203",
               "mno":"O2"
            }
         ],
         "countries":[
            {
               "countrycode":"US",
               "route":"DV8"
            }
         ]
      }
   }
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`default_route`	string	Die Standardroute, die verwendet wird, wenn keine bevorzugte Routing-Option für eine MSISDN ermittelt werden kann und keine benutzerdefinierten Routing-Regeln gelten.	false
`mnp_fallback`	boolean	Gibt an, ob MNP-Fallback aktiviert ist. Wenn aktiviert und HLR-Abfragen von einem Netzwerk nicht unterstützt werden (Konnektivitätsstatus nicht verfügbar), führt das System stattdessen eine MNP-Abfrage durch.	false
`mccmncs`	array	Eine Zuordnung von MCCMNC-Codes zu ihren automatisch ausgewählten Routen. Bei einer HLR-Abfrage für eine Nummer in einem bestimmten MCCMNC wird die entsprechende Route verwendet.	false
`mccmnc`	string(5\|6)	Eine fünf- oder sechsstellige MCCMNC-Kennung (Kombination aus Mobile Country Code und Mobile Network Code) zur Identifizierung des Mobilfunknetzbetreibers.	false
`countrycode`	string(2)	Ein zweistelliger ISO-Ländercode zur Identifizierung des Netzwerklandes.	false
`route`	string(3)	Die ausgewählte Route für das Netzwerk.	false
`mno`	string	Die kundenorientierte Marke, unter der dieses Netz betrieben wird.	false
`confidence`	string	Das Konfidenzniveau, mit dem die Auswahl getroffen wurde. Mögliche Werte sind: HIGH, NORMAL, LOW, MNP_REDIRECT. Im letzteren Fall leitet das System den Traffic zu diesem Netzwerk an MNP weiter, sofern dieses Verhalten in Ihrem Konto aktiviert ist. Andernfalls wird die Standardroute des Kontos verwendet.	false
`origin`	string	Die Quelle, auf der die Auswahl basiert. Mögliche Werte sind: `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false
`prefixes`	array	Eine Liste der in Ihrem Konto konfigurierten benutzerdefinierten präfixbasierten Routing-Regeln, falls vorhanden.	false
`countrycode`	string(2)	Ein zweistelliger ISO-Ländercode zur Identifizierung des Präfix-Landes.	false
`cns`	string	Das Präfix, für das die Routing-Regel gilt.	false
`route`	string(3)	Die ausgewählte Route für das Präfix.	false
`mccmnc`	string(5\|6)	Eine fünf- oder sechsstellige MCCMNC-Kennung (Kombination aus Mobile Country Code und Mobile Network Code) zur Identifizierung des Mobilfunknetzbetreibers.	true
`mno`	string	Die kundenorientierte Marke, unter der dieses Netz betrieben wird.	true
`countries`	array	Eine Liste der in Ihrem Konto konfigurierten benutzerdefinierten länderbasierten Regeln, falls vorhanden.	false
`countrycode`	string(2)	Ein zweistelliger ISO-Ländercode zur Identifizierung des Landes.	false
`route`	string(3)	Die ausgewählte Route für das Land.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/hlr-coverage geschützt

Liefert HLR-Abdeckungsdaten zur Unterstützung datenbasierter Entscheidungen. Dieser Endpunkt hilft Ihnen, Echtzeit-HLR-Routingoptionen über Mobilfunknetze hinweg zu analysieren, die effektivsten Pfade für Ihre Zielregionen zu identifizieren und Ihr automatisches Routing zu konfigurieren.

Empfohlene Routen von GET /route basieren auf den hier abgerufenen Abdeckungsdaten. Abdeckungsdaten sind auch auf der Seite Netzabdeckung verfügbar. Sie können Ihre Routing-Karte weiter anpassen und Regeln in Ihren Kontoeinstellungen definieren.

Wir empfehlen, sich mit diesem Leitfaden vertraut zu machen, um die Ergebnisse besser interpretieren zu können.

Anfrage Erfolgsantwort Fehlerantwort Status-Referenz

curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`countrycode`	string(2)	Ein erforderlicher zweistelliger ISO-Ländercode zum Filtern der Ergebnisse, wobei nur Datensätze zurückgegeben werden, die dem angegebenen Land zugeordnet sind.	null	erforderlich
`sample_size`	string	Ein optionaler Parameter zur Angabe einer Stichprobengröße. Mögliche Werte sind `LARGE`, `MEDIUM`, `SMALL`. Größere Stichproben decken einen längeren Zeitraum ab, kleinere Stichproben einen sehr aktuellen Zeitraum.	LARGE	optional

{
   "name":"Germany",
   "countrycode":"DE",
   "prefix":"+49",
   "mccs":[
      "262"
   ],
   "carriers":[
      {
         "mno":"Telekom",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "routes":[
            {
               "route":"V11",
               "selected":true,
               "selection_confidence":"HIGH",
               "n":361579,
               "CONNECTED":275273,
               "CONNECTED_PCT":76.13,
               "ABSENT":21529,
               "ABSENT_PCT":5.95,
               "INVALID_MSISDN":62582,
               "INVALID_MSISDN_PCT":17.3,
               "UNDETERMINED":2195,
               "UNDETERMINED_PCT":0.6
            },
            {
               "route":"E10",
               "selected":false,
               "selection_confidence":null,
               "n":122600,
               "CONNECTED":13721,
               "CONNECTED_PCT":11.19,
               "ABSENT":133,
               "ABSENT_PCT":0.1,
               "INVALID_MSISDN":55,
               "INVALID_MSISDN_PCT":0.04,
               "UNDETERMINED":108691,
               "UNDETERMINED_PCT":88.65
            }
         ]
      }
   ]
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`name`	string	Der ausgewählte Ländername in englischer Sprache als Klartext.	false
`countrycode`	string(2)	Der zweistellige ISO-Ländercode des ausgewählten Landes.	false
`prefix`	string	Die internationale Vorwahl des ausgewählten Landes.	false
`mccs`	string[]	Eine Liste von MCCs (Mobile Country Codes), die dem ausgewählten Land zugeordnet sind.	false
`carriers`	object[]	Eine Liste von Carrier-Objekten mit routenspezifischen Konnektivitätsmetriken.	false
`mno`	string	Der Name des Mobilfunknetzbetreibers in englischer Sprache als Klartext.	false
`mccmnc`	string	Der MCCMNC des Mobilfunknetzbetreibers.	false
`mcc`	string	Der MCC (Mobile Country Code) des Mobilfunknetzbetreibers.	false
`mnc`	string	Der MNC (Mobile Network Code) des Mobilfunknetzbetreibers.	false
`routes`	object[]	Eine Liste routenspezifischer Konnektivitätsergebnisse.	false
`route`	string	Die Route, auf die sich die Konnektivitätsinformationen beziehen.	false
`selected`	bool	Gibt an, ob dies die ausgewählte Route für automatisches Routing ist.	false
`selection_confidence`	string	Das Konfidenzniveau, mit dem diese Route ausgewählt wurde, d.h. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Enthält null, wenn dies nicht die ausgewählte Route ist.	true
`n`	int	Die Gesamtanzahl der Lookups in dieser Stichprobe.	false
`CONNECTED`	int	Die Anzahl der HLR-Lookups, die den Status CONNECTED zurückgegeben haben.	false
`CONNECTED_PCT`	float	Der Prozentsatz der HLR-Lookups, die den Status CONNECTED zurückgegeben haben.	false
`ABSENT`	int	Die Anzahl der HLR-Lookups, die den Status ABSENT zurückgegeben haben.	false
`ABSENT_PCT`	float	Der Prozentsatz der HLR-Lookups, die den Status ABSENT zurückgegeben haben.	false
`INVALID_MSISDN`	int	Die Anzahl der HLR-Lookups, die den Status INVALID_MSISDN zurückgegeben haben.	false
`INVALID_MSISDN_PCT`	float	Der Prozentsatz der HLR-Lookups, die den Status INVALID_MSISDN zurückgegeben haben.	false
`UNDETERMINED`	int	Die Anzahl der HLR-Lookups, die den Status UNDETERMINED zurückgegeben haben.	false
`UNDETERMINED_PCT`	float	Der Prozentsatz der HLR-Lookups, die den Status UNDETERMINED zurückgegeben haben.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Status	Beschreibung
CONNECTED	Die Nummer ist gültig und das Zielgerät ist derzeit mit dem Mobilfunknetz verbunden. Anrufe, SMS und andere Dienste sollten den Empfänger erfolgreich erreichen.
ABSENT	Die Nummer ist gültig, aber das Zielgerät ist entweder ausgeschaltet oder befindet sich vorübergehend außerhalb der Netzabdeckung. Nachrichten oder Anrufe werden möglicherweise erst zugestellt, wenn das Gerät wieder mit dem Netz verbunden ist.
INVALID_MSISDN	Die Nummer ist ungültig oder derzeit keinem Teilnehmer im Mobilfunknetz zugeordnet. Anrufe und Nachrichten an diese Nummer werden fehlschlagen.
UNDETERMINED	Der Verbindungsstatus der Nummer konnte nicht ermittelt werden. Dies kann auf eine ungültige Nummer, eine SS7-Fehlerantwort oder fehlende Konnektivität mit dem Zielnetzbetreiber zurückzuführen sein. Prüfen Sie den Fehlercode und das Beschreibungsfeld für weitere Diagnoseinformationen.

Nach oben scrollen

GET/mnp-coveragegeschützt

Dieser Endpunkt gibt eine Liste von Mobilfunknetzbetreibern mit den zugehörigen MCCMNC-Kennungen zurück, die derzeit für Rufnummernportierungsabfragen unterstützt werden.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`countrycode`	string(2)	Ein optionaler zweistelliger ISO-Ländercode zur Filterung der MCCMNC-Ergebnisse, der nur Daten für das angegebene Land zurückgibt.	null	optional

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`items[]`	array	Eine Liste von Mobilfunknetzbetreibern.	false
`country_name`	string	Der Ländername auf Englisch.	false
`country_code`	string(2)	Ein zweistelliger ISO-Ländercode.	false
`mccmnc`	string(5\|6)	Eine fünf- oder sechsstellige MCCMNC-Kennung (Kombination aus Mobile Country Code und Mobile Network Code) zur Identifizierung des Mobilfunknetzbetreibers.	false
`mcc`	string(3)	Ein dreistelliger MCC (Mobile Country Code), der das Land des Netzes repräsentiert.	false
`mnc`	string(2\|3)	Ein zwei- oder dreistelliger MNC (Mobile Network Code), der den spezifischen Mobilfunknetzbetreiber repräsentiert.	false
`brand`	string	Die kundenorientierte Marke, unter der dieses Netz betrieben wird.	true
`operator`	string	Der rechtliche Name des Mobilfunknetzbetreibers.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/price-listgeschützt

Dieser Endpunkt gibt eine Liste von Ländern zurück, in denen nur MNP-Abfragen unterstützt werden und HLR-Abfragen für diese Ziele nicht verfügbar sind.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'

{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`countries`	string[]	Eine Liste von zweistelligen ISO-Ländercodes.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/mccmncsgeschützt

Dieser Endpunkt liefert eine umfassende Liste von Mobilfunknetzbetreibern mit den zugehörigen MCCMNC-Kennungen und zusätzlichen Kontextinformationen.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`countrycode`	string(2)	Ein optionaler zweistelliger ISO-Ländercode zur Filterung der MCCMNC-Ergebnisse, der nur Datensätze des angegebenen Landes zurückgibt.	null	optional

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`items`	object[]	Eine Liste von Mobilfunknetzbetreibern.	false
`country_name`	string	Der vollständige Ländername in englischer Sprache.	false
`country_code`	string(2)	Ein zweistelliger ISO-Ländercode, der das Land des Mobilfunkbetreibers repräsentiert.	false
`mccmnc`	string(5\|6)	Eine fünf- oder sechsstellige Zeichenfolge, die den MCCMNC darstellt und den Mobilfunknetzbetreiber eindeutig identifiziert.	false
`mcc`	string(3)	Ein dreistelliger Mobile Country Code (MCC), der das Land identifiziert, in dem das Mobilfunknetz betrieben wird.	false
`mnc`	string(2\|3)	Ein zwei- oder dreistelliger Mobile Network Code (MNC), der das Mobilfunknetz innerhalb des angegebenen MCC spezifiziert.	false
`brand`	string	Der kommerzielle Markenname, unter dem das Netz betrieben wird und bei Verbrauchern bekannt ist.	true
`operator`	string	Der offizielle Name des Mobilfunknetzbetreibers, in der Regel die juristische Person, die das Netz verwaltet.	true
`parent_mccmnc`	string(5\|6)	Eine fünf- oder sechsstellige Zeichenfolge, die den MCCMNC des übergeordneten Mobilfunknetzbetreibers darstellt, falls vorhanden.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/pricegeschützt

Dieser Endpunkt gibt den Preis für eine HLR-, MNP- oder NT-Abfrage zurück.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

Anfrageparameter

Schlüssel	Typ	Beschreibung	Standard	Erforderlich
`msisdn`	string	Die Telefonnummer, für die der Preis abgerufen werden soll. Im internationalen Format.	null	erforderlich
`route_type`	string	Der Routentyp, d.h. `HLR`, `MNP`, `NT`.	null	erforderlich
`route`	string(3)	Die Route, für die der Preis berechnet werden soll. Standardmäßig wird die durch automatisches Routing ermittelte Route verwendet.	null	optional

{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`price`	object	Ein Objekt mit Preisdetails.	false
`amount`	string	Der Betrag in EUR.	false
`msisdn`	string	Die MSISDN, für die dieser Preis gilt.	false
`route_type`	string(2\|3)	Der Routentyp, für den dieser Preis gilt.	false
`route`	string(3)	Die Route, für die dieser Preis gilt.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/price-listgeschützt

Dieser Endpunkt gibt die Preise in Ihrem Konto zurück.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/price-list'

{
   "pricing":[
      {
         "route":"V11",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0090"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26201",
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26203",
         "cns":"4917821",
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"PTX",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MNP",
         "price":"0.00500"
      },
      ...
      {
         "route":"IP1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MIX",
         "price":"0.01000"
      },
      {
         "route":"LC1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"NT",
         "price":"0.00500"
      }
   ]
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`pricing`	object[]	Eine Liste von Objekten mit Preisinformationen.	false
`route`	string	Die Route, für die diese Preise gelten.	false
`countrycode`	string	Der zweistellige ISO-Ländercode, für den diese Preise bei der entsprechenden Route gelten, sofern vorhanden.	true
`countryname`	string	Der englische Ländername, der dem Ländercode entspricht, sofern vorhanden.	true
`mccmnc`	string	Der MCCMNC, für den diese Preise bei der entsprechenden Route gelten, sofern vorhanden. Überschreibt Preise auf Länderebene.	true
`cns`	string	Die Vorwahl, für die diese Preise bei der entsprechenden Route gelten, sofern vorhanden. Überschreibt Preise auf Länderebene und MCCMNC-Ebene.	true
`route_type`	string	Der entsprechende Routentyp, d. h. `HLR`, `MNP`, `NT`.	false
`route_type`	string	Der entsprechende Preis in EUR.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/balancegeschützt

Dieser Endpunkt ruft Ihren aktuellen Kontostand ab und ermöglicht es Ihnen, Prozesse basierend auf Ihrem Guthaben zu automatisieren. Er funktioniert nahtlos mit den Benachrichtigungs-E-Mails bei niedrigem Guthaben, die Sie auf Ihrer Zahlungsseite konfigurieren können.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/balance'

{
    "balance":"1002.90"
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`balance`	string	Ihr aktueller Kontostand in EUR. Ein Dezimalwert vom Typ String.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/pingöffentlich

Dieser Endpunkt sendet eine Ping-Anfrage an die API und bietet eine einfache Methode, um Ihre Verbindung zur HLR Lookups API zu testen.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/ping'

{
    "success":true
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`success`	boolean	Zeigt an, dass die Anfrage erfolgreich verarbeitet wurde.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/timeöffentlich

Dieser Endpunkt gibt einen Unix-Zeitstempel zurück, der die aktuelle Zeit auf dem HLR Lookups Server darstellt. Verwenden Sie ihn zur Synchronisierung der Uhr Ihres Servers bei der Generierung der Digest-Auth-Signatur für die Authentifizierung, um sicherzustellen, dass etwaige Abweichungen zwischen Ihrer Serverzeit und der HLR Lookups Serverzeit korrigiert werden.

Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/time'

{
    "time":1525898643
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`time`	integer	Unix-Zeitstempel, der die aktuelle HLR Lookups Serverzeit darstellt.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

GET/auth-testgeschützt

Dieser Endpunkt dient als erster Test für Ihre Basic-Auth- oder vorzugsweise Digest-Auth-Implementierung.

Basic Auth Anfrage Digest-Auth-Anfrage Erfolgsantwort Fehlerantwort

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

Anfrage-Header

Schlüssel	Typ	Beschreibung
`X-Basic`	string	SHA256-Hash von `YOUR_API_KEY:YOUR_API_SECRET`. Fügen Sie das Doppelpunkt-Symbol (:) in den Hash ein.

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Anfrage-Header

Schlüssel	Typ	Beschreibung
`X-Digest-Key`	string	Ihr HLR Lookups API-Schlüssel
`X-Digest-Signature`	string	Eindeutige Digest-Auth-Signatur (siehe Authentifizierung)
`X-Digest-Timestamp`	integer	Aktueller Unix-Zeitstempel (siehe auch `GET /time`)

{
    "success":true
}

Attribute der Erfolgsantwort

Name	Typ	Beschreibung	Nullable
`success`	boolean	Zeigt an, dass die Anfrage erfolgreich verarbeitet wurde.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Fehlerantwort-Parameter

Name	Typ	Beschreibung	Nullable
`errors[]`	string[]	Eine Liste von Zeichenketten, die den Fehler erklären.	false

Nach oben scrollen

Legacy-API-Dokumentation

Bitte beachten Sie, dass die Legacy-API veraltet ist und in Zukunft eingestellt wird. Wir empfehlen dringend, so bald wie möglich auf die aktuelle Version zu aktualisieren.

Falls Sie unsere HLR-Lookups-API zwischen 2013 und Anfang 2020 implementiert haben, verwenden Sie unsere Legacy-API. In diesem Fall lesen Sie bitte unsere Legacy-API-Dokumentation.

Legacy-API-Dokumentation

API-Dokumentation

Erste Schritte

HLR-Abfragen

MNP-Abfragen

NT-Abfragen

Routing

Preise

Tools

Erste Schritte

Verwendung der HLR Lookups API

Beispielanfrage

Beispiel-Payload

Erfolgsantwort application/json

Zusätzliche Lookup-Services

Mobile Number Portability (MNP) Lookups

Number Type Detection (NT) Lookups

Software Development Kits (SDKs)

Tools

Kein Entwickler?

Authentifizierung

API-Schlüssel und API-Secret

HTTP Basic Auth

Empfohlen: X-Basic-Header mit SHA256

Basic Auth Anfrage

Basic Authentication Header

Code-Beispiel

Anfrage-Beispiel

Anfrage-Header

Erstellen der Signatur

Digest-Signatur-Komponenten

Code-Beispiele

Konzepte

Synchrone HLR-Abfrage-API

Asynchrone HLR Lookup API

SDKs (Software Development Kits)

PHP-SDK

NodeJS-SDK

Ruby-SDK

POST/hlr-lookupgeschützt

Nutzlast

Anfrageparameter

Attribute der Erfolgsantwort

Fehlerantwort-Parameter

POST/hlr-lookupsgeschützt

Nutzlast

Anfrageparameter

Attribute der Erfolgsantwort

Fehlerantwort-Parameter

Webhook-Verarbeitung

Authentifizierung

Code-Beispiel

Empfangsbestätigung

Webhook-Payload

Webhook-Payload-Attribute

POST/mnp-lookupgeschützt

Nutzlast

Anfrageparameter

Attribute der Erfolgsantwort

Fehlerantwort-Parameter

POST/mnp-lookupsgeschützt

Nutzlast

Anfrageparameter

Attribute der Erfolgsantwort

Fehlerantwort-Parameter

Webhook-Verarbeitung

Authentifizierung

Code-Beispiel

Empfangsbestätigung

Webhook-Payload

Webhook-Payload-Attribute

POST/nt-lookupgeschützt

Nutzlast

Anfrageparameter

Attribute der Erfolgsantwort

Fehlerantwort-Parameter

POST/nt-lookups geschützt

Nutzlast

Anfrageparameter

Attribute der Erfolgsantwort

Fehlerantwort-Parameter