Aan de slag

De mondiale mobiele netwerkinfrastructuur werkt op basis van een systeem dat bekend staat als het SS7-signaleringnetwerk. Dit netwerk faciliteert de uitwisseling van abonneegegevens, oproepbesturing, SMS-verzending en real-time updates van mobiele connectiviteitsstatus tussen providers. Elk mobiel netwerk onderhoudt een Home Location Register (HLR) - een kerndatabase die essentiële gegevens over zijn abonnees opslaat.

HLR Lookup-technologie stelt bedrijven in staat om deze registers te raadplegen en actuele connectiviteits- en netwerkgegevens op te halen voor elk mobiel telefoonnummer. Dit omvat of de telefoon is ingeschakeld, aan welk netwerk deze momenteel is toegewezen, of het nummer is geporteerd, of het nummer geldig of gedeactiveerd is, en of het in roaming is.

De HLR Lookups API biedt naadloze, real-time toegang tot deze gegevens, waardoor bedrijven mobiele nummers kunnen verifiëren, routing kunnen optimaliseren en klantcommunicatie kunnen verbeteren. Deze documentatie begeleidt u bij het integreren van HLR Lookups in uw software, waardoor geautomatiseerd ophalen van real-time mobiele intelligence mogelijk wordt.

De HLR Lookups API gebruiken

Het uitvoeren van HLR Lookup-queries is snel, veilig en eenvoudig. Zodra u zich heeft aangemeld en uw API Key heeft verkregen, kunt u zich authenticeren en directe lookups starten met eenvoudige HTTP POST-verzoeken, via POST /hlr-lookup. Als alternatief kunt u grote datasets verwerken door te kiezen voor snelle asynchrone API-verzoeken met resultaten die via webhook naar uw server worden teruggestuurd, zoals uitgelegd in de sectie concepten.

Voorbeeldverzoek

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"

Authenticatie wordt geleverd via HTTP-headers, en payload.json moet (minimaal) het volgende JSON-object bevatten:

Voorbeeld Payload

{
   "msisdn": "+14156226819"
}

Bij succesvolle uitvoering ontvangt u een respons met real-time connectiviteitsgegevens voor het opgegeven mobiele nummer.

Succesvolle Respons 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"
}

Voor een volledige uiteenzetting van verzoek- en responsattributen en connectiviteitsstatussen, zie POST /hlr-lookup.

Aanvullende Lookup-diensten

Mobile Number Portability (MNP) Lookups

Gebruik MNP-lookups om netwerkeigendom en portabiliteitsgegevens te bepalen zonder real-time connectiviteit op te vragen. Als u alleen de MCCMNC van een nummer nodig heeft, raadpleeg dan POST /mnp-lookup.

Number Type Detection (NT) Lookups

Bepaal of een telefoonnummer toebehoort aan een vast nummer, mobiel, premium-tarief, VoIP, pager of andere nummerplanreeksen met POST /nt-lookup.

Software Development Kits (SDK's)

De HLR Lookups API werkt met elke REST-client in elke programmeertaal en we hebben SDK's gepubliceerd voor PHP, Ruby en NodeJS op onze GitHub om u snel op weg te helpen.

Tools

Om een naadloze ontwikkelervaring te garanderen, bieden we een uitgebreid pakket tools, waaronder in-browser API-verzoek- en webhookmonitoring, IP-adres whitelisting, robuuste authenticatie-opties en een authenticatie-testendpoint.

Geen ontwikkelaar?

HLR Lookups en Number Portability Queries kunnen worden uitgevoerd zonder enige programmering. Lees meer over onze enterprise webclient en browser-gebaseerde rapportagefuncties.

Authenticatie

Om de beveiliging en juiste toegangscontrole te waarborgen, vereisen de meeste verzoeken aan de HLR Lookups API authenticatie. Endpoints zijn ingedeeld als publiek of beveiligd. Bij het benaderen van een beveiligd endpoint moet uw verzoek worden geauthenticeerd met uw API-sleutel en -geheim via de Digest-Auth of Basic-Auth methode. Digest-Auth is de veiligere optie en wordt sterk aanbevolen. Gebruik het GET /auth-test endpoint om uw authenticatie-instellingen te verifiëren.

API-sleutel en API-geheim

Verkrijg uw API-sleutel en -geheim via de pagina API-instellingen. U kunt ook uw gewenste authenticatiemethode configureren en IP-adres whitelisting inschakelen voor extra beveiliging. Als u vermoedt dat uw API-geheim gecompromitteerd is, kunt u op elk moment een nieuw geheim genereren.

Basic Auth Digest Auth IP-whitelist

Standaard Basic Authentication is eenvoudig te implementeren en breed ondersteund. U kunt authenticeren door uw API-sleutel en -geheim als user:pass paar in het HTTP-verzoek mee te sturen.

HTTP Basic Auth

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

Dit verstuurt een Authorization header:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Aanbevolen: X-Basic Header met SHA256

Voor verbeterde beveiliging kunt u een SHA256-hash van uw inloggegevens versturen in plaats van deze direct als base64 te verzenden. Om deze methode te gebruiken, berekent u de hash van uw YOUR_API_KEY:YOUR_API_SECRET paar en verstuurt u deze via de X-Basic header:

Basic Auth Verzoek

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

Basic Authentication headers

Sleutel	Type	Omschrijving
`X-Basic`	string	SHA256-hash van `YOUR_API_KEY:YOUR_API_SECRET`. Neem het dubbele punt symbool (:) op in de hash.	verplicht

Codevoorbeeld

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

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

Digest-Auth is de aanbevolen methode voor het beveiligen van toegang tot beveiligde HLR Lookup API-endpoints. Elk verzoek moet de volgende headers bevatten: X-Digest-Key, X-Digest-Signature en X-Digest-Timestamp, die hieronder worden toegelicht.

Verzoekvoorbeeld

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"

Verzoek headers

Sleutel	Type	Omschrijving
`X-Digest-Key`	string	Uw unieke HLR Lookups API-sleutel.	verplicht
`X-Digest-Signature`	string	Een unieke authenticatiehandtekening (zie hieronder).	verplicht
`X-Digest-Timestamp`	integer	Huidige Unix-tijdstempel (zie ook `GET /time`).	verplicht

Samenstellen van de handtekening

De X-Digest-Signature wordt gemaakt met behulp van een SHA256 HMAC-hash, met uw API-geheim als gedeelde sleutel.

De te hashen string is als volgt gestructureerd:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Het . symbool staat voor string-concatenatie.

Digest handtekening componenten

Component	Type	Omschrijving
`ENDPOINT_PATH`	string	Het opgevraagde API-endpoint, bijv. `/auth-test` in kleine letters.
`UNIX_TIMESTAMP`	integer	Huidige Unix-tijdstempel (moet binnen 30 seconden zijn). Zie `GET /time`.
`REQUEST_METHOD`	string	De gebruikte HTTP-methode, bijv. `POST` of `GET`.
`REQUEST_BODY`	string	Request body data. Stel in op `null` voor `GET` verzoeken.

Codevoorbeelden

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)

Scroll Omhoog

Concepten

Het implementeren van HLR Lookups in elke programmeertaal of systeem via onze HTTP REST API is eenvoudig en efficiënt. Met een eenvoudig integratieproces kunt u direct mobiele netwerken in real-time bevragen voor directe inzichten in de geldigheid van telefoonnummers, connectiviteitsstatus en routeringsinformatie.

De keuze voor de juiste API hangt af van uw specifieke toepassing. Als u real-time lookup-resultaten nodig heeft voor toepassingen zoals VoIP-telefonie, fraudedetectie of SMS-routering, is de synchrone API de beste keuze. Als uw toepassing echter grootschalige verwerking, bulk lookups of grootschalige dataverificatie betreft, biedt de asynchrone API geoptimaliseerde prestaties met bandbreedte-efficiëntie en batch lookup-mogelijkheden.

Configureer de API om een van onze aangepaste routeringsopties te gebruiken voor optimale snelheid, nauwkeurigheid en kosteneffectiviteit. U kunt lookup-resultaten ook opslaan in opslaglocaties voor eenvoudige CSV- en JSON-rapportdownloads, evenals geavanceerde analyses via de webinterface.

Synchrone HLR Lookup API

Het POST /hlr-lookup endpoint verwerkt één mobiel telefoonnummer (MSISDN) per verzoek en retourneert de resultaten direct in de HTTP-responsebody. De resultaten zijn geformatteerd als JSON en zijn ideaal voor real-time toepassingen, waaronder validatie van mobiele nummers, oproeproutering en SMS-berichtbezorging.

Een synchrone API-aanroep bestaat uit een direct HTTP-verzoek en -antwoord. Uw systeem stuurt één MSISDN (mobiel nummer) per verzoek en ontvangt een onmiddellijk antwoord met real-time HLR lookup-resultaten in JSON-formaat. Deze API is geoptimaliseerd voor toepassingen die directe verificatie en connectiviteitscontroles vereisen, zoals fraudedetectie, VoIP-oproeproutering en optimalisatie van SMS-gateways.

Asynchrone HLR Lookup API

Het POST /hlr-lookups endpoint is ontworpen voor bulk- en grootschalige verwerking, waarmee u tot 1,000 MSISDN's per verzoek kunt indienen. In plaats van resultaten direct te retourneren, gebruikt deze API geautomatiseerde webhooks om resultaten progressief naar uw server te verzenden. Lookup-resultaten worden als JSON-objecten geretourneerd via HTTP POST-callbacks.

De asynchrone API is geoptimaliseerd voor snelheid, efficiëntie en schaalbaarheid. Het elimineert netwerklatentieproblemen die gepaard gaan met synchrone aanroepen, waardoor het ideaal is voor bedrijven die hoge doorvoer van lookups nodig hebben. Uw systeem dient tot 1,000 MSISDN's per verzoek in, en ons platform verwerkt deze parallel en levert de resultaten terug naar uw server via HTTP-webhooks in batches van maximaal 1,000 resultaten per callback.

SDK's (Software Development Kits)

Onze Software Development Kits (SDK's) voor PHP, NodeJS en Ruby stroomlijnen het integratieproces, waardoor u efficiënt en met minimale inspanning verbinding kunt maken met de HLR Lookups API.

Deze SDK's bieden kant-en-klare functies, authenticatiebeheer en gestructureerde API-verzoeksjablonen, waardoor de ontwikkeltijd wordt verkort en best practices worden gewaarborgd.

Bekijk onze volledige lijst met beschikbare SDK's op GitHub en start vandaag nog met integreren.

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);

Bekijk op GitHub 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   }

Bekijk op GitHub 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)

Bekijk op GitHub README.md

Scroll Omhoog

POST/hlr-lookupbeveiligd

Voert een synchrone HLR Lookup uit en levert real-time connectiviteits- en portabiliteitsgegevens van mobiele telefoonnummers rechtstreeks van netwerkoperators. Dit endpoint is ideaal voor live verkeersscenario's waarbij tijdgevoelige applicaties directe verificatie vereisen of een telefoonnummer momenteel bereikbaar is (verbonden) of onbeschikbaar (uitgeschakeld). Daarnaast helpt het om actieve nummers te onderscheiden van ongeldige, onbekende of valse nummers.

Voor bulkverwerking van grote datasets die geen directe resultaten vereisen, kunt u overwegen het asynchrone POST /hlr-lookups te gebruiken, dat geoptimaliseerd is voor snelle batchverwerking.

Als uw primaire focus ligt op het ophalen van mobiele nummerportabiliteitsgegevens (MCCMNC) en u geen live connectiviteitsstatus nodig heeft, biedt het POST /mnp-lookup een kosteneffectief alternatief voor mobiele nummerportabiliteitsquery's.

Verzoek Succesvolle Respons Foutrespons Statusreferentie

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

Payload

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`msisdn`	string	Het mobiele telefoonnummer (MSISDN) dat opgevraagd moet worden, in internationaal formaat (bijv. +14156226819 of 0014156226819). Landcodes zijn verplicht.	null	verplicht
`route`	string(3)	Een optionele identificatie van drie tekens die de route voor deze lookup specificeert. Stel in op `null` of laat deze parameter weg om uw aangepaste routeringsmap toe te passen of laat ons systeem automatisch de beste route bepalen voor deze lookup.	null	optioneel
`storage`	string	Een optionele opslagidentificatie die het rapport specificeert waar resultaten worden opgeslagen voor handmatige controle, analyse en rapportage. Het systeem voegt automatisch een tijdstempel toe met de huidige maand. Indien weggelaten of ingesteld op `null`, groepeert het systeem resultaten automatisch per maand voor rapportagedoeleinden.	null	optioneel

{
   "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"
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`id`	string(12)	Een unieke identificatiecode die aan dit opzoekverzoek is toegewezen.	false
`msisdn`	string	Het mobiele telefoonnummer dat wordt opgevraagd, geformatteerd in internationaal formaat (bijv. +14156226819 of 0014156226819).	false
`connectivity_status`	string	Geeft aan of de connectiviteitsstatus van het nummer succesvol is opgehaald. Mogelijke waarden: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` of `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Een vijf- of zescijferige Mobile Country Code (MCC) en Mobile Network Code (MNC) die het netwerk identificeren dat momenteel aan het telefoonnummer is gekoppeld.	true
`mcc`	string(3)	Een driecijferige Mobile Country Code (MCC) die het land identificeert waar het telefoonnummer is geregistreerd.	true
`mnc`	string(2\|3)	Een twee- of driecijferige Mobile Network Code (MNC) die het specifieke netwerk identificeert waartoe het telefoonnummer behoort.	true
`imsi`	string	De International Mobile Subscriber Identity (IMSI), een unieke identificatiecode voor de SIM-kaart die aan dit nummer is gekoppeld. Beschikbaarheid is afhankelijk van de netwerkconfiguratie.	true
`msin`	string(10)	Het Mobile Subscription Identification Number (MSIN) binnen de database van de mobiele operator. Beschikbaarheid is afhankelijk van de netwerkconfiguratie.	true
`msc`	string(12)	De Mobile Switching Center (MSC) die momenteel de communicatie van deze abonnee afhandelt. Beschikbaarheid is afhankelijk van de netwerkconfiguratie.	true
`original_network_name`	string	De oorspronkelijke (native) netwerkoperator die aan dit nummer is gekoppeld.	true
`original_country_name`	string	De volledige naam van het land waar het mobiele telefoonnummer oorspronkelijk is geregistreerd, weergegeven in het Engels.	true
`original_country_code`	string(2)	De tweeletterige ISO-landcode die het land vertegenwoordigt waar het telefoonnummer oorspronkelijk is toegewezen.	true
`original_country_prefix`	string	De internationale kiescode (landnummer) die overeenkomt met het oorspronkelijke land van het mobiele telefoonnummer.	true
`is_ported`	boolean	Geeft aan of het mobiele nummer is geporteerd van het oorspronkelijke netwerk naar een andere operator.	true
`ported_network_name`	string	De naam van de netwerkoperator waarnaar het mobiele nummer is geporteerd, indien van toepassing.	true
`ported_country_name`	string	De naam van het land waarnaar het mobiele nummer is geporteerd, indien van toepassing.	true
`ported_country_code`	string(2)	De tweeletterige ISO-landcode die het land vertegenwoordigt waarnaar het mobiele nummer is geporteerd, indien van toepassing.	true
`ported_country_prefix`	string	De internationale kiescode (landnummer) voor het land waarnaar het mobiele nummer is geporteerd, indien van toepassing.	true
`is_roaming`	boolean	Geeft aan of het mobiele nummer momenteel roamt op een buitenlands netwerk. Beschikbaarheid van roamingstatus is afhankelijk van de mobiele netwerkoperator.	true
`roaming_network_name`	string	De naam van het netwerk waarop het mobiele nummer momenteel roamt, indien van toepassing.	true
`roaming_country_name`	string	De naam van het land waar het mobiele nummer momenteel roamt, indien van toepassing.	true
`roaming_country_code`	string(2)	De tweeletterige ISO-landcode van het land waar het mobiele nummer momenteel roamt, indien van toepassing.	true
`roaming_country_prefix`	string	De internationale kiescode (landnummer) van het land waar het mobiele nummer momenteel roamt, indien van toepassing.	true
`cost`	string	Een decimale waarde weergegeven als string, die de opzoekkosten in EUR aangeeft.	true
`timestamp`	string	Een W3C-geformatteerde tijdstempel inclusief tijdzone, die aangeeft wanneer de opzoekopdracht is voltooid.	true
`storage`	string	De naam van de opslag waar de opzoekresultaten zijn opgeslagen. Dit komt overeen met rapportnamen en CSV-downloads die beschikbaar zijn via de webinterface.	true
`route`	string(3)	Een drieletterige identificatiecode die de routeringsmethode aangeeft die voor dit opzoekverzoek is gebruikt.	true
`processing_status`	string	Het verwerkingsresultaat van de opzoekopdracht. Mogelijke waarden: `COMPLETED` (succesvol), `REJECTED` (netwerk onbereikbaar, geen kosten in rekening gebracht) of `FAILED` (fout opgetreden tijdens verwerking).	false
`error_code`	integer	Een optionele interne foutcode die aanvullende diagnostische informatie biedt voor klantenondersteuning.	true
`error_description`	string	Een korte uitleg van de gegeven foutcode (indien van toepassing) in platte Engelse tekst.	true
`data_source`	string	De gegevensbron die voor dit verzoek is gebruikt. Mogelijke waarden: `LIVE_HLR` (realtime HLR-query) of `MNP_DB` (statische database voor nummerportabiliteit). Raadpleeg routeringsopties voor details.	false
`routing_instruction`	string	Een door dubbele punten gescheiden string die de routeringsinstructie beschrijft die in het verzoek is gebruikt. Het eerste onderdeel is `STATIC` wanneer u een route heeft opgegeven of `AUTO` voor automatische routering; het tweede onderdeel is de route-identificatie, en bij automatische routeringsverzoeken toont een derde onderdeel de oorsprong waarop de routeringsbeslissing is gebaseerd (d.w.z. `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."
    ]
}

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Status	Omschrijving
CONNECTED	Het nummer is geldig en het toestel is momenteel verbonden met het mobiele netwerk. Oproepen, SMS en andere diensten zouden de ontvanger succesvol moeten bereiken.
ABSENT	Het nummer is geldig, maar het toestel is uitgeschakeld of tijdelijk buiten bereik van het netwerk. Berichten of oproepen worden mogelijk niet afgeleverd totdat het apparaat opnieuw verbinding maakt met het netwerk.
INVALID_MSISDN	Het nummer is ongeldig of momenteel niet toegewezen aan een abonnee op het mobiele netwerk. Oproepen en berichten naar dit nummer zullen mislukken.
UNDETERMINED	De connectiviteitsstatus van het nummer kon niet worden bepaald. Dit kan het gevolg zijn van een ongeldig nummer, een SS7-foutrespons of een gebrek aan connectiviteit met de doelnetwerk operator. Raadpleeg de foutcode en het bijbehorende beschrijvingsveld voor aanvullende diagnostiek.

Scroll Omhoog

POST/hlr-lookupsbeveiligd

Initieert een batch van asynchrone HLR-lookups, waarbij live mobiele telefoon connectiviteits- en portabiliteitsgegevens worden opgehaald van netwerkoperators. Resultaten worden via webhooks naar uw server geleverd. Deze methode is geoptimaliseerd voor het verwerken van grote volumes nummers die geen onmiddellijke respons vereisen, zoals database-opschoning en verificatie. Voor real-time toepassingen zoals oproep-routering of SMS-bezorging kunt u overwegen om in plaats daarvan het POST /hlr-lookup endpoint te gebruiken.

Dit endpoint is ideaal voor bulkverwerking wanneer het doel is om telefoonnummers te identificeren die momenteel bereikbaar zijn (verbonden) of niet beschikbaar (telefoon uitgeschakeld), terwijl ongeldige, niet-toegewezen of valse nummers worden uitgefilterd. Daarnaast biedt het live portabiliteitsstatus (MCCMNC) naast connectiviteitsgegevens.

Voordat u dit endpoint gebruikt, moet u ervoor zorgen dat een webhook-URL is geconfigureerd om lookup-resultaten asynchroon te ontvangen. U kunt dit instellen in uw API-instellingen.

Verzoek Succesvolle Respons Foutrespons Webhooks Statusreferentie

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

Payload

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`msisdns`	array	Een array van mobiele telefoonnummers (MSISDN's) in internationaal formaat (bijv. +14156226819 of 0014156226819). U kunt maximaal 1000 nummers per verzoek opnemen.	null	verplicht
`route`	string(3)	Een optionele identificatie van drie tekens die de route voor deze lookup specificeert. Stel in op `null` of laat deze parameter weg om uw aangepaste routeringsmap toe te passen of laat ons systeem automatisch de beste route bepalen voor deze lookup.	null	optioneel
`storage`	string	Een optionele opslagidentificatie die het rapport specificeert waar resultaten worden opgeslagen voor handmatige controle, analyse en rapportage. Het systeem voegt automatisch een tijdstempel toe met de huidige maand. Indien weggelaten of ingesteld op `null`, groepeert het systeem resultaten automatisch per maand voor rapportagedoeleinden.	null	optioneel

{
   "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"
   ]
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`accepted`	array	Een lijst met objecten die unieke identificaties en MSISDN's bevatten die zijn geaccepteerd voor verwerking.	false
`accepted_count`	integer	Het totale aantal MSISDN's dat succesvol is geaccepteerd voor verwerking.	false
`rejected`	array	Een lijst met objecten die unieke identificaties en MSISDN's bevatten die zijn afgewezen voor verwerking, meestal vanwege ongeldige nummers. Voor afgewezen items worden geen kosten in rekening gebracht.	false
`rejected_count`	integer	Het totale aantal MSISDN's dat is afgewezen vanwege validatiefouten.	false
`total_count`	integer	Het totale aantal geaccepteerde en afgewezen MSISDN's dat is ingediend voor verwerking.	false
`cost`	string	Een decimale waarde weergegeven als string, die de totale kosten in EUR aangeeft voor de geaccepteerde lookups.	false
`storage`	string	De naam van de opslag waar de lookup-resultaten worden toegevoegd, gebruikt voor rapportage en CSV-downloads via de webinterface.	false
`route`	string(3\|4)	Een drie- of viertekens identificatie die de route specificeert die voor dit lookup-verzoek wordt gebruikt. Bevat AUTO als op nummers gebaseerde automatische routering is aangevraagd.	false
`webhook_urls`	array	De webhook-URL's die zijn geconfigureerd in uw API-instellingen. Resultaten worden hier teruggestuurd.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Webhooks verwerken

Na verzending begint ons platform met het verwerken van de opgegeven telefoonnummers en stuurt de resultaten naar de eerder opgegeven webhook-URL op uw server. De resultaten worden verzonden als een HTTP POST-verzoek met een JSON-object in de body van het verzoek.

Authenticatie

Authenticeer de webhook door de X-Signatures HTTP-header te controleren.

De X-Signatures-header bevat een door puntkomma's gescheiden lijst met handtekeningen. Elke handtekening in de lijst wordt gegenereerd met een van de API-secrets die in uw account zijn geconfigureerd. Om de webhook te verifiëren, genereert u een SHA-256-hash met uw API-key, secret en de onbewerkte HTTP-body - vergelijk deze vervolgens met de handtekeningen in de lijst.

Een overeenkomst bevestigt dat het verzoek authentiek is en ondertekend met een secret die u beheert.

Codevoorbeeld

$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;
    }
}

Het verzoek is geldig als een van de handtekeningen in de header overeenkomt met een SHA256-hash berekend over de aaneengeschakelde string van uw API-key, secret en de HTTP-body.

Ontvangst bevestigen

Uw server dient te reageren met HTTP-statuscode 200 OK om succesvolle ontvangst te bevestigen. Indien een andere statuscode wordt geretourneerd, een time-out optreedt (10 seconden) of een ander bezorgprobleem ontstaat, zal het systeem de webhook automatisch na één minuut opnieuw proberen. Als het verzoek blijft mislukken, volgen nieuwe pogingen een exponentiële backoff-strategie, met volgende pogingen na 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minuten.

Dit herpogingsmechanisme garandeert maximale betrouwbaarheid bij het afleveren van opzoekresultaten naar uw infrastructuur. Het minimaliseert het risico op gegevensverlies door tijdelijke netwerkproblemen of serveruitval.

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 Attributen

Het JSON-object bevat een attribuut type => HLR naast een attribuut results dat een lijst met lookup-objecten bevat, zoals hieronder gedocumenteerd.

Naam	Type	Omschrijving	Nullable
`id`	string(12)	Een unieke identificatiecode die aan dit opzoekverzoek is toegewezen.	false
`msisdn`	string	Het mobiele telefoonnummer dat wordt opgevraagd, geformatteerd in internationaal formaat (bijv. +14156226819 of 0014156226819).	false
`connectivity_status`	string	Geeft aan of de connectiviteitsstatus van het nummer succesvol is opgehaald. Mogelijke waarden: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` of `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Een vijf- of zescijferige Mobile Country Code (MCC) en Mobile Network Code (MNC) die het netwerk identificeren dat momenteel aan het telefoonnummer is gekoppeld.	true
`mcc`	string(3)	Een driecijferige Mobile Country Code (MCC) die het land identificeert waar het telefoonnummer is geregistreerd.	true
`mnc`	string(2\|3)	Een twee- of driecijferige Mobile Network Code (MNC) die het specifieke netwerk identificeert waartoe het telefoonnummer behoort.	true
`imsi`	string	De International Mobile Subscriber Identity (IMSI), een unieke identificatiecode voor de SIM-kaart die aan dit nummer is gekoppeld. Beschikbaarheid is afhankelijk van de netwerkconfiguratie.	true
`msin`	string(10)	Het Mobile Subscription Identification Number (MSIN) binnen de database van de mobiele operator. Beschikbaarheid is afhankelijk van de netwerkconfiguratie.	true
`msc`	string(12)	De Mobile Switching Center (MSC) die momenteel de communicatie van deze abonnee afhandelt. Beschikbaarheid is afhankelijk van de netwerkconfiguratie.	true
`original_network_name`	string	De oorspronkelijke (native) netwerkoperator die aan dit nummer is gekoppeld.	true
`original_country_name`	string	De volledige naam van het land waar het mobiele telefoonnummer oorspronkelijk is geregistreerd, weergegeven in het Engels.	true
`original_country_code`	string(2)	De tweeletterige ISO-landcode die het land vertegenwoordigt waar het telefoonnummer oorspronkelijk is toegewezen.	true
`original_country_prefix`	string	De internationale kiescode (landnummer) die overeenkomt met het oorspronkelijke land van het mobiele telefoonnummer.	true
`is_ported`	boolean	Geeft aan of het mobiele nummer is geporteerd van het oorspronkelijke netwerk naar een andere operator.	true
`ported_network_name`	string	De naam van de netwerkoperator waarnaar het mobiele nummer is geporteerd, indien van toepassing.	true
`ported_country_name`	string	De naam van het land waarnaar het mobiele nummer is geporteerd, indien van toepassing.	true
`ported_country_code`	string(2)	De tweeletterige ISO-landcode die het land vertegenwoordigt waarnaar het mobiele nummer is geporteerd, indien van toepassing.	true
`ported_country_prefix`	string	De internationale kiescode (landnummer) voor het land waarnaar het mobiele nummer is geporteerd, indien van toepassing.	true
`is_roaming`	boolean	Geeft aan of het mobiele nummer momenteel roamt op een buitenlands netwerk. Beschikbaarheid van roamingstatus is afhankelijk van de mobiele netwerkoperator.	true
`roaming_network_name`	string	De naam van het netwerk waarop het mobiele nummer momenteel roamt, indien van toepassing.	true
`roaming_country_name`	string	De naam van het land waar het mobiele nummer momenteel roamt, indien van toepassing.	true
`roaming_country_code`	string(2)	De tweeletterige ISO-landcode van het land waar het mobiele nummer momenteel roamt, indien van toepassing.	true
`roaming_country_prefix`	string	De internationale kiescode (landnummer) van het land waar het mobiele nummer momenteel roamt, indien van toepassing.	true
`cost`	string	Een decimale waarde weergegeven als string, die de opzoekkosten in EUR aangeeft.	true
`timestamp`	string	Een W3C-geformatteerde tijdstempel inclusief tijdzone, die aangeeft wanneer de opzoekopdracht is voltooid.	true
`storage`	string	De naam van de opslag waar de opzoekresultaten zijn opgeslagen. Dit komt overeen met rapportnamen en CSV-downloads die beschikbaar zijn via de webinterface.	true
`route`	string(3)	Een drieletterige identificatiecode die de routeringsmethode aangeeft die voor dit opzoekverzoek is gebruikt.	true
`processing_status`	string	Het verwerkingsresultaat van de opzoekopdracht. Mogelijke waarden: `COMPLETED` (succesvol), `REJECTED` (netwerk onbereikbaar, geen kosten in rekening gebracht) of `FAILED` (fout opgetreden tijdens verwerking).	false
`error_code`	integer	Een optionele interne foutcode die aanvullende diagnostische informatie biedt voor klantenondersteuning.	true
`error_description`	string	Een korte uitleg van de gegeven foutcode (indien van toepassing) in platte Engelse tekst.	true
`data_source`	string	De gegevensbron die voor dit verzoek is gebruikt. Mogelijke waarden: `LIVE_HLR` (realtime HLR-query) of `MNP_DB` (statische database voor nummerportabiliteit). Raadpleeg routeringsopties voor details.	false
`routing_instruction`	string	Een door dubbele punten gescheiden string die de routeringsinstructie beschrijft die in het verzoek is gebruikt. Het eerste onderdeel is `STATIC` wanneer u een route heeft opgegeven of `AUTO` voor automatische routering; het tweede onderdeel is de route-identificatie, en bij automatische routeringsverzoeken toont een derde onderdeel de oorsprong waarop de routeringsbeslissing is gebaseerd (d.w.z. `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	Omschrijving
CONNECTED	Het nummer is geldig en het toestel is momenteel verbonden met het mobiele netwerk. Oproepen, SMS en andere diensten zouden de ontvanger succesvol moeten bereiken.
ABSENT	Het nummer is geldig, maar het toestel is uitgeschakeld of tijdelijk buiten bereik van het netwerk. Berichten of oproepen worden mogelijk niet afgeleverd totdat het apparaat opnieuw verbinding maakt met het netwerk.
INVALID_MSISDN	Het nummer is ongeldig of momenteel niet toegewezen aan een abonnee op het mobiele netwerk. Oproepen en berichten naar dit nummer zullen mislukken.
UNDETERMINED	De connectiviteitsstatus van het nummer kon niet worden bepaald. Dit kan het gevolg zijn van een ongeldig nummer, een SS7-foutrespons of een gebrek aan connectiviteit met de doelnetwerk operator. Raadpleeg de foutcode en het bijbehorende beschrijvingsveld voor aanvullende diagnostiek.

Scroll Omhoog

POST/mnp-lookupbeveiligd

Voert een synchrone MNP-lookup uit en levert informatie over nummerportabiliteit en netwerk. Dit endpoint is geschikt wanneer uw primaire doel is om de huidige MCCMNC van een mobiel telefoonnummer te achterhalen en het oorspronkelijke en huidige netwerk real-time te bepalen.

Voor bulkverwerking van grote datasets die geen directe resultaten vereisen, kunt u overwegen het asynchrone POST /mnp-lookups te gebruiken, dat geoptimaliseerd is voor snelle batchverwerking.

MNP-queries bepalen betrouwbaar de portabiliteit en netwerkinformatie, maar geven niet aan of de mobiele telefoon momenteel verbonden is met een netwerk en bereikbaar is. Om actuele connectiviteitsinformatie te verkrijgen, gebruikt u in plaats daarvan het POST /hlr-lookup endpoint.

Verzoek Succesvolle Respons Foutrespons

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

Payload

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`msisdn`	string	Het mobiele telefoonnummer (MSISDN) dat opgevraagd moet worden, in internationaal formaat (bijv. +14156226819 of 0014156226819). Landcodes zijn verplicht.	null	verplicht
`route`	string(3)	Een optionele identificatie van drie tekens die de route voor deze lookup specificeert. Stel in op `null` of laat deze parameter weg om uw aangepaste routeringsmap toe te passen of laat ons systeem automatisch de beste route bepalen voor deze lookup.	null	optioneel
`storage`	string	Een optionele opslagidentificatie die het rapport specificeert waar resultaten worden opgeslagen voor handmatige controle, analyse en rapportage. Het systeem voegt automatisch een tijdstempel toe met de huidige maand. Indien weggelaten of ingesteld op `null`, groepeert het systeem resultaten automatisch per maand voor rapportagedoeleinden.	null	optioneel

{
   "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
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`id`	string(12)	Een unieke identificatiecode van 12 tekens voor deze opzoeking.	false
`msisdn`	string	Het mobiele telefoonnummer dat in dit opzoekverzoek is geëvalueerd.	false
`query_status`	string	Geeft aan of het ophalen van portabiliteits- en netwerkinformatie geslaagd is. Mogelijke waarden zijn `OK` of `FAILED`.	false
`mccmnc`	string(5\|6)	Een MCCMNC-code van vijf of zes tekens (combinatie van mobiele landcode en mobiele netwerkcode) die het netwerk identificeert waartoe het mobiele telefoonnummer momenteel behoort.	true
`mcc`	string(3)	Een MCC-code van drie tekens (mobiele landcode) die het land vertegenwoordigt dat is gekoppeld aan het huidige netwerk van het mobiele telefoonnummer.	true
`mnc`	string(2\|3)	Een MNC-code van twee of drie tekens (mobiele netwerkcode) die de huidige netwerkoperator voor het mobiele telefoonnummer identificeert.	true
`is_ported`	boolean	Geeft aan of het telefoonnummer is geporteerd van het oorspronkelijke netwerk naar een nieuwe operator.	true
`original_network_name`	string	Een willekeurige tekenreeks (in het Engels) die de naam van de oorspronkelijke netwerkoperator van het geïnspecteerde mobiele telefoonnummer specificeert.	true
`original_country_name`	string	Een willekeurige tekenreeks (in het Engels) die het oorspronkelijke land van het geïnspecteerde mobiele telefoonnummer aangeeft.	true
`original_country_code`	string(2)	Een ISO-landcode van twee tekens die het oorspronkelijke land van het geïnspecteerde mobiele telefoonnummer vertegenwoordigt.	true
`original_country_prefix`	string	Het kengetal van het oorspronkelijke land dat is gekoppeld aan het geïnspecteerde mobiele telefoonnummer.	true
`ported_network_name`	string	Specificeert de netwerkoperator waarnaar het geïnspecteerde mobiele telefoonnummer is geporteerd, indien van toepassing.	true
`ported_country_name`	string	Specificeert het land waarnaar het geïnspecteerde mobiele telefoonnummer is geporteerd, indien van toepassing.	true
`ported_country_code`	string(2)	Een ISO-landcode van twee tekens die het land vertegenwoordigt waarnaar het geïnspecteerde mobiele telefoonnummer is geporteerd, indien van toepassing.	true
`ported_country_prefix`	string	Het kengetal van het land waarnaar het geïnspecteerde mobiele telefoonnummer is geporteerd, indien van toepassing.	true
`extra`	string	Een willekeurige tekenreeks met optionele aanvullende details over het telefoonnummer.	true
`cost`	string	Een decimale waarde, weergegeven als tekenreeks, die de kosten in EUR voor deze opzoeking aangeeft.	true
`timestamp`	string	Een W3C-tijdstempel, inclusief tijdzone-informatie, die aangeeft wanneer de opzoeking is voltooid.	true
`storage`	string	De opslagnaam (of rapportnaam) waaraan de opzoekresultaten zijn toegevoegd. Deze wordt gebruikt voor CSV-downloads en rapportage via de webinterface.	true
`route`	string(3)	Een identificatiecode van drie tekens die de route specificeert die voor dit opzoekverzoek is gebruikt.	true
`error_code`	integer	Een optionele interne foutcode die aanvullende context biedt voor diagnostiek door klantenondersteuning.	true

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

POST/mnp-lookupsbeveiligd

Initieert een batch van asynchrone MNP (mobiele nummerportabiliteit) lookups, waarbij de huidige MCCMNC wordt opgehaald en de oorspronkelijke en huidige netwerken in real-time worden bepaald. Resultaten worden via webhooks naar uw server geleverd. Deze methode is geoptimaliseerd voor het verwerken van grote volumes nummers die geen onmiddellijke respons vereisen, zoals database-opschoning en verificatie. Voor real-time toepassingen zoals oproep-routering of SMS-bezorging kunt u overwegen om in plaats daarvan het POST /mnp-lookup endpoint te gebruiken.

MNP-queries bepalen betrouwbaar de portabiliteit en netwerkinformatie, maar geven niet aan of de mobiele telefoon momenteel verbonden is met een netwerk en bereikbaar is. Om actuele connectiviteitsinformatie te verkrijgen, gebruikt u in plaats daarvan het POST /hlr-lookups endpoint.

Voordat u dit endpoint gebruikt, moet u ervoor zorgen dat een webhook-URL is geconfigureerd om lookup-resultaten asynchroon te ontvangen. U kunt dit instellen in uw API-instellingen.

Verzoek Succesvolle Respons Foutrespons Webhooks

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

Payload

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`msisdns`	array	Een array van mobiele telefoonnummers (MSISDN's) in internationaal formaat (bijv. +14156226819 of 0014156226819). U kunt maximaal 1000 nummers per verzoek opnemen.	null	verplicht
`route`	string(3)	Een optionele drie-tekens identifier die de route voor deze lookup specificeert. Stel in op `null` of laat deze parameter weg om uw aangepaste routeringsmap toe te passen of om ons systeem automatisch de beste routes voor dit verzoek te laten bepalen.	null	optioneel
`storage`	string	Een optionele opslagidentificatie die het rapport specificeert waar resultaten worden opgeslagen voor handmatige controle, analyse en rapportage. Het systeem voegt automatisch een tijdstempel toe met de huidige maand. Indien weggelaten of ingesteld op `null`, groepeert het systeem resultaten automatisch per maand voor rapportagedoeleinden.	null	optioneel

{
   "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"
   ]
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`accepted`	array	Een lijst met objecten die unieke identificaties en MSISDN's bevatten die zijn geaccepteerd voor verwerking.	false
`accepted_count`	integer	Het totale aantal MSISDN's dat succesvol is geaccepteerd voor verwerking.	false
`rejected`	array	Een lijst met objecten die unieke identificaties en MSISDN's bevatten die zijn afgewezen voor verwerking, meestal vanwege ongeldige nummers. Voor afgewezen items worden geen kosten in rekening gebracht.	false
`rejected_count`	integer	Het totale aantal MSISDN's dat is afgewezen vanwege validatiefouten.	false
`total_count`	integer	Het totale aantal geaccepteerde en afgewezen MSISDN's dat is ingediend voor verwerking.	false
`cost`	string	Een decimale waarde weergegeven als string, die de totale kosten in EUR aangeeft voor de geaccepteerde lookups.	false
`storage`	string	De naam van de opslag waar de lookup-resultaten worden toegevoegd, gebruikt voor rapportage en CSV-downloads via de webinterface.	false
`route`	string(3)	Een identificatiecode van drie tekens die de route specificeert die voor dit opzoekverzoek is gebruikt.	false
`webhook_urls`	array	De webhook-URL's die zijn geconfigureerd in uw API-instellingen. Resultaten worden hier teruggestuurd.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Webhooks verwerken

Na verzending begint ons platform met het verwerken van de opgegeven telefoonnummers en stuurt de resultaten naar de eerder opgegeven webhook-URL op uw server. De resultaten worden verzonden als een HTTP POST-verzoek met een JSON-object in de body van het verzoek.

Authenticatie

Authenticeer de webhook door de X-Signatures HTTP-header te controleren.

De X-Signatures-header bevat een door puntkomma's gescheiden lijst met handtekeningen. Elke handtekening in de lijst wordt gegenereerd met een van de API-secrets die in uw account zijn geconfigureerd. Om de webhook te verifiëren, genereert u een SHA-256-hash met uw API-key, secret en de onbewerkte HTTP-body - vergelijk deze vervolgens met de handtekeningen in de lijst.

Een overeenkomst bevestigt dat het verzoek authentiek is en ondertekend met een secret die u beheert.

Codevoorbeeld

$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;
    }
}

Het verzoek is geldig als een van de handtekeningen in de header overeenkomt met een SHA256-hash berekend over de aaneengeschakelde string van uw API-key, secret en de HTTP-body.

Ontvangst bevestigen

Uw server dient te reageren met HTTP-statuscode 200 OK om succesvolle ontvangst te bevestigen. Indien een andere statuscode wordt geretourneerd, een time-out optreedt (10 seconden) of een ander bezorgprobleem ontstaat, zal het systeem de webhook automatisch na één minuut opnieuw proberen. Als het verzoek blijft mislukken, volgen nieuwe pogingen een exponentiële backoff-strategie, met volgende pogingen na 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minuten.

Dit herpogingsmechanisme garandeert maximale betrouwbaarheid bij het afleveren van opzoekresultaten naar uw infrastructuur. Het minimaliseert het risico op gegevensverlies door tijdelijke netwerkproblemen of serveruitval.

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 Attributen

Het JSON-object bevat een attribuut type => MNP naast een attribuut results dat een lijst met lookup-objecten bevat, zoals hieronder gedocumenteerd.

Naam	Type	Omschrijving	Nullable
`id`	string(12)	Een unieke identificatiecode van 12 tekens voor deze opzoeking.	false
`msisdn`	string	Het mobiele telefoonnummer dat in dit opzoekverzoek is geëvalueerd.	false
`query_status`	string	Geeft aan of het ophalen van portabiliteits- en netwerkinformatie geslaagd is. Mogelijke waarden zijn `OK` of `FAILED`.	false
`mccmnc`	string(5\|6)	Een MCCMNC-code van vijf of zes tekens (combinatie van mobiele landcode en mobiele netwerkcode) die het netwerk identificeert waartoe het mobiele telefoonnummer momenteel behoort.	true
`mcc`	string(3)	Een MCC-code van drie tekens (mobiele landcode) die het land vertegenwoordigt dat is gekoppeld aan het huidige netwerk van het mobiele telefoonnummer.	true
`mnc`	string(2\|3)	Een MNC-code van twee of drie tekens (mobiele netwerkcode) die de huidige netwerkoperator voor het mobiele telefoonnummer identificeert.	true
`is_ported`	boolean	Geeft aan of het telefoonnummer is geporteerd van het oorspronkelijke netwerk naar een nieuwe operator.	true
`original_network_name`	string	Een willekeurige tekenreeks (in het Engels) die de naam van de oorspronkelijke netwerkoperator van het geïnspecteerde mobiele telefoonnummer specificeert.	true
`original_country_name`	string	Een willekeurige tekenreeks (in het Engels) die het oorspronkelijke land van het geïnspecteerde mobiele telefoonnummer aangeeft.	true
`original_country_code`	string(2)	Een ISO-landcode van twee tekens die het oorspronkelijke land van het geïnspecteerde mobiele telefoonnummer vertegenwoordigt.	true
`original_country_prefix`	string	Het kengetal van het oorspronkelijke land dat is gekoppeld aan het geïnspecteerde mobiele telefoonnummer.	true
`ported_network_name`	string	Specificeert de netwerkoperator waarnaar het geïnspecteerde mobiele telefoonnummer is geporteerd, indien van toepassing.	true
`ported_country_name`	string	Specificeert het land waarnaar het geïnspecteerde mobiele telefoonnummer is geporteerd, indien van toepassing.	true
`ported_country_code`	string(2)	Een ISO-landcode van twee tekens die het land vertegenwoordigt waarnaar het geïnspecteerde mobiele telefoonnummer is geporteerd, indien van toepassing.	true
`ported_country_prefix`	string	Het kengetal van het land waarnaar het geïnspecteerde mobiele telefoonnummer is geporteerd, indien van toepassing.	true
`extra`	string	Een willekeurige tekenreeks met optionele aanvullende details over het telefoonnummer.	true
`cost`	string	Een decimale waarde, weergegeven als tekenreeks, die de kosten in EUR voor deze opzoeking aangeeft.	true
`timestamp`	string	Een W3C-tijdstempel, inclusief tijdzone-informatie, die aangeeft wanneer de opzoeking is voltooid.	true
`storage`	string	De opslagnaam (of rapportnaam) waaraan de opzoekresultaten zijn toegevoegd. Deze wordt gebruikt voor CSV-downloads en rapportage via de webinterface.	true
`route`	string(3)	Een identificatiecode van drie tekens die de route specificeert die voor dit opzoekverzoek is gebruikt.	true
`error_code`	integer	Een optionele interne foutcode die aanvullende context biedt voor diagnostiek door klantenondersteuning.	true

Scroll Omhoog

POST/nt-lookupbeveiligd

Voert een synchrone nummertype (NT) opzoeking uit. Dit endpoint is ideaal als uw primaire doel is om in real-time te bepalen of de opgegeven telefoonnummers behoren tot vaste lijnen, mobiele nummers, premium rate, VoIP, pagers of andere nummerplanreeksen.

NT-opzoekingen detecteren betrouwbaar het telefoonnummertype, maar geven niet aan of het doelnummer momenteel verbonden is met een netwerk en bereikbaar is. Gebruik het POST /hlr-lookup endpoint om actuele connectiviteitsinformatie op te halen.

Als uw use case accurate netwerk- en portabiliteitsinformatie (MCCMNC) vereist maar geen actuele connectiviteitsstatus, gebruik dan het POST /mnp-lookup endpoint voor mobiele nummerportabiliteitsopzoekingen.

Verzoek Succesvolle Respons Foutrespons Typereferentie

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

Payload

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`number`	string	Een telefoonnummer in internationaal formaat (bijv. +4989702626 of 004989702626).	null	mandatory
`route`	string(3)	Een optionele identificatiecode van drie tekens die de route voor deze opzoeking specificeert. Stel in op `null` of laat deze parameter weg om uw aangepaste routeringsmap toe te passen of om ons systeem automatisch de beste routes voor dit verzoek te laten bepalen.	null	optioneel
`storage`	string	Een optionele opslagidentificatie die het rapport specificeert waar resultaten worden opgeslagen voor handmatige controle, analyse en rapportage. Het systeem voegt automatisch een tijdstempel toe met de huidige maand. Indien weggelaten of ingesteld op `null`, groepeert het systeem resultaten automatisch per maand voor rapportagedoeleinden.	null	optioneel

{
     "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"
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`id`	string(12)	Een unieke identificatiecode die aan dit opzoekverzoek is toegewezen.	false
`number`	string	Het telefoonnummer dat tijdens deze opzoekaanvraag is geëvalueerd.	false
`number_type`	string	Het gedetecteerde nummertype. Mogelijke waarden zijn: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Geeft aan of de nummertypeinformatie succesvol is verkregen. Retourneert `OK` bij succes, of `FAILED` als de opzoeking is mislukt.	false
`is_valid`	boolean	Geeft aan of het telefoonnummer syntactisch geldig is.	true
`invalid_reason`	string	Een Engelstalig bericht in platte tekst dat aangeeft waarom het telefoonnummer als ongeldig wordt beschouwd (bijv. "too short" of "invalid prefix"), of `null` als het nummer geldig is.	true
`is_possibly_ported`	boolean	Geeft aan of het telefoonnummer mogelijk is overgedragen van de oorspronkelijke operator naar een andere provider. Voor definitieve porteerbaarheidsinformatie gebruikt u MNP-opzoekingen.	true
`is_vanity_number`	boolean	Geeft aan of het telefoonnummer een vanity-nummer is, wat betekent dat het alfabetische tekens bevat.	true
`qualifies_for_hlr_lookup`	boolean	Geeft aan of het telefoonnummer in aanmerking komt voor aanvullende opzoekingen via HLR-opzoekingen.	true
`mccmnc`	string(5\|6)	Een tekenreeks van vijf of zes tekens die de MCCMNC-tuple (mobiele landcode en mobiele netwerkcode) vertegenwoordigt die het oorspronkelijke netwerk van het mobiele telefoonnummer identificeert.	true
`mcc`	string(3)	Een tekenreeks van drie tekens die de MCC (mobiele landcode) vertegenwoordigt die het land identificeert dat is gekoppeld aan het oorspronkelijke mobiele netwerk van het telefoonnummer.	true
`mnc`	string(2\|3)	Een tekenreeks van twee of drie tekens die de MNC (mobiele netwerkcode) vertegenwoordigt die de oorspronkelijke mobiele netwerkoperator van het telefoonnummer identificeert.	true
`original_network_name`	string	Een willekeurige Engelstalige tekenreeks in platte tekst die de naam van de oorspronkelijke netwerkoperator van het geïnspecteerde mobiele telefoonnummer specificeert.	true
`original_country_name`	string	Een willekeurige Engelstalige tekenreeks in platte tekst die het oorspronkelijke land specificeert dat is gekoppeld aan het geïnspecteerde mobiele telefoonnummer.	true
`original_country_code`	string(2)	Een ISO-landcode van twee tekens die het oorspronkelijke land van het geïnspecteerde mobiele telefoonnummer aangeeft.	true
`regions`	array	Een lijst met leesbare Engelstalige tekenreeksen die de geografische regio('s) specificeren die aan dit telefoonnummer zijn gekoppeld.	true
`timezones`	array	Een lijst met tijdzones (in Olson-formaat) die aan dit telefoonnummer zijn gekoppeld.	true
`info_text`	string	Een willekeurige tekenreeks die aanvullende informatie over het telefoonnummer kan bevatten.	true
`cost`	string	Een decimale waarde weergegeven als tekenreeks, die de kosten (in EUR) van deze opzoeking aangeeft.	true
`timestamp`	string	Een W3C-geformatteerde tijdstempel (inclusief tijdzone) die aangeeft wanneer de opzoeking is voltooid.	true
`storage`	string	Specificeert de opslaglocatie waar de opzoekresultaten zijn toegevoegd. Dit komt overeen met de rapportnaam die wordt gebruikt voor CSV-downloads en analyses via de webinterface.	true
`route`	string(3)	Een identificatiecode van drie tekens die de route specificeert die voor dit opzoekverzoek is gebruikt.	true

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Type	Omschrijving
LANDLINE	Vast telefoonnummer.
MOBILE	Mobiel telefoonnummer. Geschikt voor HLR-lookups om aanvullende informatie over verbindingsstatus, netwerk, portabiliteit en roaming te verkrijgen.
MOBILE_OR_LANDLINE	Vast of mobiel telefoonnummer. Mogelijk geschikt voor HLR-lookup.
TOLL_FREE	Gratis telefoonnummer.
PREMIUM_RATE	Betaalnummer met extra kosten.
SHARED_COST	Gedeelde kosten telefoonnummer. Doorgaans goedkoper dan betaalnummers.
VOIP	Voice over IP telefoonnummer. Inclusief TSoIP-nummers (Telephony Service over IP).
PAGER	Semafoon nummer. Doorgaans zonder spraakfunctionaliteit.
UAN	Univeral Access Number (bedrijfsnummer). Kan doorgeschakeld worden naar specifieke vestigingen, maar maakt het mogelijk één nummer voor het hele bedrijf te gebruiken.
VOICEMAIL	Voicemail telefoonnummer.
UNKNOWN	Nummertype kon niet worden bepaald.

Scroll Omhoog

POST/nt-lookups beveiligd

Dit endpoint voert een reeks asynchrone nummertype-opzoekingen uit waarbij de resultaten via webhook naar uw server worden teruggestuurd. Het is geschikt als uw primaire doel is om te bepalen of gegeven telefoonnummers behoren tot vaste lijnen, mobiele nummers, betaalnummers, VoIP, pagers of andere nummerplanreeksen. Geoptimaliseerd voor snelle verwerking van grote volumes nummers, is dit endpoint ideaal voor bulkbewerkingen (bijv. database-opschoning). Voor live verkeer en tijdkritische toepassingen kunt u het POST /nt-lookup endpoint gebruiken.

U moet een webhook-URL opgeven in uw API-instellingen als voorwaarde om dit endpoint aan te roepen.

Verzoek Succesvolle Respons Foutrespons Webhooks Typereferentie

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

Payload

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`numbers`	array	Een array van telefoonnummers in internationaal formaat (bijv. +14156226819 of 004989702626). Maximaal 1000 nummers kunnen per verzoek worden opgenomen.	null	verplicht
`route`	string(3)	Een optionele identifier van drie tekens die de route voor deze opzoeking specificeert. Stel in op `null` of laat deze parameter weg om uw aangepaste routeringsmap toe te passen of om ons systeem automatisch de beste route voor dit verzoek te laten bepalen.	null	optioneel
`storage`	string	Een optionele opslagidentificatie die het rapport specificeert waar resultaten worden opgeslagen voor handmatige controle, analyse en rapportage. Het systeem voegt automatisch een tijdstempel toe met de huidige maand. Indien weggelaten of ingesteld op `null`, groepeert het systeem resultaten automatisch per maand voor rapportagedoeleinden.	null	optioneel

{
   "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"
   ]
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`accepted`	array	Een array van objecten, elk met een unieke identifier en een telefoonnummer dat is geaccepteerd voor verwerking.	false
`accepted_count`	integer	Het totaal aantal telefoonnummers dat is geaccepteerd voor verwerking.	false
`rejected`	array	Een array van objecten, elk met een unieke identifier en een telefoonnummer dat is geweigerd voor verwerking. Doorgaans zijn deze nummers ongeldig en worden er geen kosten in rekening gebracht.	false
`rejected_count`	integer	Het totaal aantal telefoonnummers dat is geweigerd voor verwerking.	false
`total_count`	integer	Het totaal aantal geaccepteerde en geweigerde telefoonnummers dat is ingediend voor verwerking.	false
`cost`	string	Een string die een decimale waarde vertegenwoordigt welke de kosten in EUR voor deze opzoekingen aangeeft.	false
`storage`	string	De naam van de opslag (rapport) waar de opzoekresultaten aan zijn toegevoegd. Deze naam wordt gebruikt voor CSV-downloads en analyses via de webinterface.	false
`route`	string(3)	Een identifier van drie tekens die de route specificeert die voor dit opzoekverzoek is gebruikt.	false
`webhook_urls`	array	De webhook-URL's die zijn geconfigureerd in uw API-instellingen. Resultaten worden hier teruggestuurd.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Webhooks verwerken

Na verzending begint ons platform met het verwerken van de opgegeven telefoonnummers en stuurt de resultaten naar de eerder opgegeven webhook-URL op uw server. De resultaten worden verzonden als een HTTP POST-verzoek met een JSON-object in de body van het verzoek.

Authenticatie

Authenticeer de webhook door de X-Signatures HTTP-header te controleren.

De X-Signatures-header bevat een door puntkomma's gescheiden lijst met handtekeningen. Elke handtekening in de lijst wordt gegenereerd met een van de API-secrets die in uw account zijn geconfigureerd. Om de webhook te verifiëren, genereert u een SHA-256-hash met uw API-key, secret en de onbewerkte HTTP-body - vergelijk deze vervolgens met de handtekeningen in de lijst.

Een overeenkomst bevestigt dat het verzoek authentiek is en ondertekend met een secret die u beheert.

Codevoorbeeld

$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;
    }
}

Het verzoek is geldig als een van de handtekeningen in de header overeenkomt met een SHA256-hash berekend over de aaneengeschakelde string van uw API-key, secret en de HTTP-body.

Ontvangst bevestigen

Uw server dient te reageren met HTTP-statuscode 200 OK om succesvolle ontvangst te bevestigen. Indien een andere statuscode wordt geretourneerd, een time-out optreedt (10 seconden) of een ander bezorgprobleem ontstaat, zal het systeem de webhook automatisch na één minuut opnieuw proberen. Als het verzoek blijft mislukken, volgen nieuwe pogingen een exponentiële backoff-strategie, met volgende pogingen na 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minuten.

Dit herpogingsmechanisme garandeert maximale betrouwbaarheid bij het afleveren van opzoekresultaten naar uw infrastructuur. Het minimaliseert het risico op gegevensverlies door tijdelijke netwerkproblemen of serveruitval.

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 Attributen

Het JSON-object bevat een attribuut type => NT naast een attribuut results dat een lijst met lookup-objecten bevat, zoals hieronder gedocumenteerd.

Naam	Type	Omschrijving	Nullable
`id`	string(12)	Een unieke identificatiecode die aan dit opzoekverzoek is toegewezen.	false
`number`	string	Het telefoonnummer dat tijdens deze opzoekaanvraag is geëvalueerd.	false
`number_type`	string	Het gedetecteerde nummertype. Mogelijke waarden zijn: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Geeft aan of de nummertypeinformatie succesvol is verkregen. Retourneert `OK` bij succes, of `FAILED` als de opzoeking is mislukt.	false
`is_valid`	boolean	Geeft aan of het telefoonnummer syntactisch geldig is.	true
`invalid_reason`	string	Een Engelstalig bericht in platte tekst dat aangeeft waarom het telefoonnummer als ongeldig wordt beschouwd (bijv. "too short" of "invalid prefix"), of `null` als het nummer geldig is.	true
`is_possibly_ported`	boolean	Geeft aan of het telefoonnummer mogelijk is overgedragen van de oorspronkelijke operator naar een andere provider. Voor definitieve porteerbaarheidsinformatie gebruikt u MNP-opzoekingen.	true
`is_vanity_number`	boolean	Geeft aan of het telefoonnummer een vanity-nummer is, wat betekent dat het alfabetische tekens bevat.	true
`qualifies_for_hlr_lookup`	boolean	Geeft aan of het telefoonnummer in aanmerking komt voor aanvullende opzoekingen via HLR-opzoekingen.	true
`mccmnc`	string(5\|6)	Een tekenreeks van vijf of zes tekens die de MCCMNC-tuple (mobiele landcode en mobiele netwerkcode) vertegenwoordigt die het oorspronkelijke netwerk van het mobiele telefoonnummer identificeert.	true
`mcc`	string(3)	Een tekenreeks van drie tekens die de MCC (mobiele landcode) vertegenwoordigt die het land identificeert dat is gekoppeld aan het oorspronkelijke mobiele netwerk van het telefoonnummer.	true
`mnc`	string(2\|3)	Een tekenreeks van twee of drie tekens die de MNC (mobiele netwerkcode) vertegenwoordigt die de oorspronkelijke mobiele netwerkoperator van het telefoonnummer identificeert.	true
`original_network_name`	string	Een willekeurige Engelstalige tekenreeks in platte tekst die de naam van de oorspronkelijke netwerkoperator van het geïnspecteerde mobiele telefoonnummer specificeert.	true
`original_country_name`	string	Een willekeurige Engelstalige tekenreeks in platte tekst die het oorspronkelijke land specificeert dat is gekoppeld aan het geïnspecteerde mobiele telefoonnummer.	true
`original_country_code`	string(2)	Een ISO-landcode van twee tekens die het oorspronkelijke land van het geïnspecteerde mobiele telefoonnummer aangeeft.	true
`regions`	array	Een lijst met leesbare Engelstalige tekenreeksen die de geografische regio('s) specificeren die aan dit telefoonnummer zijn gekoppeld.	true
`timezones`	array	Een lijst met tijdzones (in Olson-formaat) die aan dit telefoonnummer zijn gekoppeld.	true
`info_text`	string	Een willekeurige tekenreeks die aanvullende informatie over het telefoonnummer kan bevatten.	true
`cost`	string	Een decimale waarde weergegeven als tekenreeks, die de kosten (in EUR) van deze opzoeking aangeeft.	true
`timestamp`	string	Een W3C-geformatteerde tijdstempel (inclusief tijdzone) die aangeeft wanneer de opzoeking is voltooid.	true
`storage`	string	Specificeert de opslaglocatie waar de opzoekresultaten zijn toegevoegd. Dit komt overeen met de rapportnaam die wordt gebruikt voor CSV-downloads en analyses via de webinterface.	true
`route`	string(3)	Een identificatiecode van drie tekens die de route specificeert die voor dit opzoekverzoek is gebruikt.	true

Type	Omschrijving
LANDLINE	Vast telefoonnummer.
MOBILE	Mobiel telefoonnummer. Geschikt voor HLR-lookups om aanvullende informatie over verbindingsstatus, netwerk, portabiliteit en roaming te verkrijgen.
MOBILE_OR_LANDLINE	Vast of mobiel telefoonnummer. Mogelijk geschikt voor HLR-lookup.
TOLL_FREE	Gratis telefoonnummer.
PREMIUM_RATE	Betaalnummer met extra kosten.
SHARED_COST	Gedeelde kosten telefoonnummer. Doorgaans goedkoper dan betaalnummers.
VOIP	Voice over IP telefoonnummer. Inclusief TSoIP-nummers (Telephony Service over IP).
PAGER	Semafoon nummer. Doorgaans zonder spraakfunctionaliteit.
UAN	Univeral Access Number (bedrijfsnummer). Kan doorgeschakeld worden naar specifieke vestigingen, maar maakt het mogelijk één nummer voor het hele bedrijf te gebruiken.
VOICEMAIL	Voicemail telefoonnummer.
UNKNOWN	Nummertype kon niet worden bepaald.

Scroll Omhoog

GET/routebeveiligd

Haalt de route op die automatisch wordt geselecteerd wanneer u een HLR-lookup uitvoert zonder de route parameter op te geven.

Automatische routeselectie is gebaseerd op de routeringskaart die opvraagbaar is via het GET /hlr-coverage endpoint, welke voornamelijk is afgeleid van GET /routing-map. U kunt uw routeringskaart aanpassen en aangepaste regels definiëren in uw accountinstellingen.

Verzoek Succesvolle Respons Foutrespons

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`msisdn`	string	Het MSISDN waarvoor de automatisch geselecteerde routeringsinformatie moet worden opgehaald.	null	verplicht

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

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`route`	string	De aanbevolen route.	false
`confidence_level`	string	Het betrouwbaarheidsniveau waarmee deze route is geselecteerd, d.w.z. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	De op nummerplan gebaseerde MCCMNC voor dit nummer.	false
`origin`	string	De oorsprong waarop de routeringsbeslissing is gebaseerd, d.w.z. `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."
    ]
}

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/routesbeveiligd

Dit endpoint retourneert een lijst van beschikbare HLR-, MNP- en NT-routes. Elke route, inclusief de bijbehorende functies en beperkingen, wordt toegelicht op de pagina routeringsdetails.

Verzoek Succesvolle Respons Foutrespons

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

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

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`routes`	object	Een object met routes gegroepeerd op routetype.	false
`HLR\|MNP\|NT`	string[]	Bevat een lijst van route-identificaties.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/routing-mapbeveiligd

Haalt de geautomatiseerde routeringsconfiguratie op die momenteel wordt toegepast op HLR Lookups voor uw account. Deze standaardconfiguratie wordt gebruikt wanneer u HLR lookups indient zonder een route parameter op te geven. U kunt uw routeringsoverzicht aanpassen en aangepaste regels maken in uw accountinstellingen.

De configuratiehiërarchie loopt van landspecifieke regels naar MCCMNC-specifieke regels, en uiteindelijk naar individuele telefoonnummerprefix-toewijzingen. In de praktijk betekent dit dat individuele telefoonnummerprefix-toewijzingen voorrang hebben op conflicterende MCCMNC-toewijzingen, die op hun beurt landspecifieke regels overschrijven. Let op dat MNP fallback eventuele conflicterende aangepaste regels overschrijft wanneer deze is ingeschakeld.

Verzoek Succesvolle Respons Foutrespons

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"
            }
         ]
      }
   }
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`default_route`	string	De standaardroute die wordt gebruikt wanneer geen voorkeursrouteringsoptie kan worden bepaald voor een MSISDN en er geen aangepaste routeringsregels van toepassing zijn.	false
`mnp_fallback`	boolean	Geeft aan of MNP fallback is ingeschakeld. Wanneer ingeschakeld en HLR queries niet worden ondersteund door een netwerk (connectiviteitsstatus niet beschikbaar), voert het systeem in plaats daarvan een MNP lookup uit.	false
`mccmncs`	array	Een overzicht van MCCMNC-codes naar hun automatisch geselecteerde routes. Bij het uitvoeren van een HLR lookup voor een nummer in een bepaalde MCCMNC wordt de bijbehorende route gebruikt.	false
`mccmnc`	string(5\|6)	Een vijf- of zesletterige MCCMNC (combinatie van mobile country code en mobile network code) die de mobiele netwerkoperator identificeert.	false
`countrycode`	string(2)	Een ISO-landcode van twee tekens die het land van het netwerk identificeert.	false
`route`	string(3)	De geselecteerde route voor het netwerk.	false
`mno`	string	Het consumentgerichte merk waaronder dit netwerk opereert.	false
`confidence`	string	Het betrouwbaarheidsniveau waarmee de selectie is gemaakt. Mogelijke waarden zijn: HIGH, NORMAL, LOW, MNP_REDIRECT. In het laatste geval leidt het systeem verkeer naar dit netwerk om naar MNP, als dit gedrag is ingeschakeld in uw account. Anders gebruikt het de standaardroute in het account.	false
`origin`	string	De oorsprong waarop de selectie is gebaseerd. Mogelijke waarden zijn: `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	Een lijst van aangepaste prefix-gebaseerde routeringsregels die in uw account zijn geconfigureerd, indien aanwezig.	false
`countrycode`	string(2)	Een ISO-landcode van twee tekens die het land van de prefix identificeert.	false
`cns`	string	De prefix waarop de routeringsregel van toepassing is.	false
`route`	string(3)	De geselecteerde route voor de prefix.	false
`mccmnc`	string(5\|6)	Een vijf- of zesletterige MCCMNC (combinatie van mobile country code en mobile network code) die de mobiele netwerkoperator identificeert.	true
`mno`	string	Het consumentgerichte merk waaronder dit netwerk opereert.	true
`countries`	array	Een lijst van aangepaste landspecifieke regels die in uw account zijn geconfigureerd, indien aanwezig.	false
`countrycode`	string(2)	Een ISO-landcode van twee tekens die het land identificeert.	false
`route`	string(3)	De geselecteerde route voor het land.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/hlr-coverage beveiligd

Geeft HLR-dekkingsinzichten om datagedreven besluitvorming te ondersteunen. Dit endpoint helpt u real-time HLR-routeringsopties over mobiele netwerken te analyseren, de meest effectieve paden voor uw doelregio's te identificeren en uw automatische routering te configureren.

Aanbevolen routes van GET /route zijn gebaseerd op de dekkingsgegevens die hier worden opgehaald. Dekkingsgegevens zijn ook beschikbaar op de pagina netwerkdekking. U kunt uw routeringskaart verder aanpassen en regels definiëren in uw accountinstellingen.

We raden aan om uzelf vertrouwd te maken met deze handleiding om de resultaten te helpen interpreteren.

Verzoek Succesvolle Respons Foutrespons Statusreferentie

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`countrycode`	string(2)	Een verplichte tweeletterige ISO-landcode die wordt gebruikt om resultaten te filteren, waarbij alleen records worden geretourneerd die aan het opgegeven land zijn gekoppeld.	null	verplicht
`sample_size`	string	Een optionele parameter die een steekproefgrootte specificeert. Mogelijke waarden zijn `LARGE`, `MEDIUM`, `SMALL`. Grotere steekproeven bestrijken een langere tijdsperiode, kleinere steekproeven bestrijken een zeer recente tijdsperiode.	LARGE	optioneel

{
   "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
            }
         ]
      }
   ]
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`name`	string	De naam van het geselecteerde land in gewone Engelse tekst.	false
`countrycode`	string(2)	De tweeletterige ISO-landcode van het geselecteerde land.	false
`prefix`	string	Het internationale kiesvoorvoegsel van het geselecteerde land.	false
`mccs`	string[]	Een lijst met MCC's (mobile country codes) die aan het geselecteerde land zijn gekoppeld.	false
`carriers`	object[]	Een lijst met provider-objecten met routespecifieke connectiviteitsmetrieken.	false
`mno`	string	De naam van de mobiele netwerkoperator in gewone Engelse tekst.	false
`mccmnc`	string	De MCCMNC van de mobiele netwerkoperator.	false
`mcc`	string	De MCC (mobile country code) van de mobiele netwerkoperator.	false
`mnc`	string	De MNC (mobile network code) van de mobiele netwerkoperator.	false
`routes`	object[]	Een lijst met routespecifieke connectiviteitsresultaten.	false
`route`	string	De route waarop de connectiviteitsinformatie van toepassing is.	false
`selected`	bool	Geeft aan of dit de geselecteerde route is voor geautomatiseerde routering.	false
`selection_confidence`	string	Het betrouwbaarheidsniveau waarmee deze route is geselecteerd, d.w.z. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Bevat null als dit niet de geselecteerde route is.	true
`n`	int	Het totale aantal lookups in deze steekproef.	false
`CONNECTED`	int	Het aantal HLR-lookups dat een CONNECTED-status heeft geretourneerd.	false
`CONNECTED_PCT`	float	Het percentage HLR-lookups dat een CONNECTED-status heeft geretourneerd.	false
`ABSENT`	int	Het aantal HLR-lookups dat een ABSENT-status heeft geretourneerd.	false
`ABSENT_PCT`	float	Het percentage HLR-lookups dat een ABSENT-status heeft geretourneerd.	false
`INVALID_MSISDN`	int	Het aantal HLR-lookups dat een INVALID_MSISDN-status heeft geretourneerd.	false
`INVALID_MSISDN_PCT`	float	Het percentage HLR-lookups dat een INVALID_MSISDN-status heeft geretourneerd.	false
`UNDETERMINED`	int	Het aantal HLR-lookups dat een UNDETERMINED-status heeft geretourneerd.	false
`UNDETERMINED_PCT`	float	Het percentage HLR-lookups dat een UNDETERMINED-status heeft geretourneerd.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Status	Omschrijving
CONNECTED	Het nummer is geldig en het toestel is momenteel verbonden met het mobiele netwerk. Oproepen, SMS en andere diensten zouden de ontvanger succesvol moeten bereiken.
ABSENT	Het nummer is geldig, maar het toestel is uitgeschakeld of tijdelijk buiten bereik van het netwerk. Berichten of oproepen worden mogelijk niet afgeleverd totdat het apparaat opnieuw verbinding maakt met het netwerk.
INVALID_MSISDN	Het nummer is ongeldig of momenteel niet toegewezen aan een abonnee op het mobiele netwerk. Oproepen en berichten naar dit nummer zullen mislukken.
UNDETERMINED	De connectiviteitsstatus van het nummer kon niet worden bepaald. Dit kan het gevolg zijn van een ongeldig nummer, een SS7-foutrespons of een gebrek aan connectiviteit met de doelnetwerk operator. Raadpleeg de foutcode en het bijbehorende beschrijvingsveld voor aanvullende diagnostiek.

Scroll Omhoog

GET/mnp-coveragebeveiligd

Dit endpoint retourneert een lijst van mobiele netwerkoperators, samen met hun bijbehorende MCCMNC-identificatiecodes, die momenteel worden ondersteund voor nummerportabiliteit lookups.

Verzoek Succesvolle Respons Foutrespons

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`countrycode`	string(2)	Een optionele tweeletterige ISO-landcode om de MCCMNC-resultaten te filteren, waarbij alleen gegevens worden geretourneerd die relevant zijn voor het opgegeven land.	null	optioneel

{
   "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"
      }
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`items[]`	array	Een lijst van mobiele netwerkoperators.	false
`country_name`	string	De landnaam in het Engels.	false
`country_code`	string(2)	Een tweeletterige ISO-landcode.	false
`mccmnc`	string(5\|6)	Een vijf- of zesletterige MCCMNC (combinatie van mobile country code en mobile network code) die de mobiele netwerkoperator identificeert.	false
`mcc`	string(3)	Een drieletterige MCC (mobile country code) die het land van het netwerk vertegenwoordigt.	false
`mnc`	string(2\|3)	Een twee- of drieletterige MNC (mobile network code) die de specifieke mobiele netwerkoperator vertegenwoordigt.	false
`brand`	string	Het consumentgerichte merk waaronder dit netwerk opereert.	true
`operator`	string	De juridische naam van de mobiele netwerkoperator.	true

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/price-listbeveiligd

Dit endpoint retourneert een lijst van landen waar alleen MNP-lookups worden ondersteund en HLR-queries niet beschikbaar zijn voor deze bestemmingen.

Verzoek Succesvolle Respons Foutrespons

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

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

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`countries`	string[]	Een lijst van ISO-landcodes bestaande uit twee tekens.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/mccmncsbeveiligd

Dit endpoint retourneert een uitgebreide lijst van mobiele netwerkoperators met hun bijbehorende MCCMNC-identificatiecodes en aanvullende contextuele informatie.

Verzoek Succesvolle Respons Foutrespons

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`countrycode`	string(2)	Een optionele tweeletterige ISO-landcode die wordt gebruikt om MCCMNC-resultaten te filteren, waarbij alleen records worden geretourneerd die zijn gekoppeld aan het opgegeven land.	null	optioneel

{
   "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"
      }
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`items`	object[]	Een lijst van mobiele netwerkoperators.	false
`country_name`	string	De volledige landnaam in het Engels.	false
`country_code`	string(2)	Een tweeletterige ISO-landcode die het land van de mobiele operator vertegenwoordigt.	false
`mccmnc`	string(5\|6)	Een vijf- of zesletterige tekenreeks die de MCCMNC vertegenwoordigt, welke de mobiele netwerkoperator uniek identificeert.	false
`mcc`	string(3)	Een drieletterige Mobile Country Code (MCC) die het land identificeert waar het mobiele netwerk actief is.	false
`mnc`	string(2\|3)	Een twee- of drieletterige Mobile Network Code (MNC) die het mobiele netwerk binnen de gegeven MCC specificeert.	false
`brand`	string	De commerciële merknaam waaronder het netwerk opereert en door consumenten wordt herkend.	true
`operator`	string	De officiële naam van de mobiele netwerkoperator, doorgaans de juridische entiteit die het netwerk beheert.	true
`parent_mccmnc`	string(5\|6)	Een vijf- of zesletterige tekenreeks die de MCCMNC van de moedermaatschappij van de mobiele netwerkoperator vertegenwoordigt, indien van toepassing.	true

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/pricebeveiligd

Dit endpoint retourneert de prijs voor een HLR-, MNP- of NT-lookup.

Verzoek Succesvolle Respons Foutrespons

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

Verzoekparameters

Sleutel	Type	Omschrijving	Standaard	Verplicht
`msisdn`	string	Het telefoonnummer waarvoor de prijs moet worden opgehaald. In internationaal formaat.	null	verplicht
`route_type`	string	Het routetype, d.w.z. `HLR`, `MNP`, `NT`.	null	verplicht
`route`	string(3)	De route waarvoor de prijs moet worden berekend. Standaard wordt de route gebruikt die door geautomatiseerde routering is bepaald.	null	optioneel

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

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`price`	object	Een object met prijsdetails.	false
`amount`	string	Het bedrag in EUR.	false
`msisdn`	string	Het MSISDN waarvoor deze prijs geldt.	false
`route_type`	string(2\|3)	Het routetype waarvoor deze prijs geldt.	false
`route`	string(3)	De route waarvoor deze prijs geldt.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/price-listbeveiligd

Dit endpoint retourneert de prijzen in uw account.

Verzoek Succesvolle Respons Foutrespons

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"
      }
   ]
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`pricing`	object[]	Een lijst met objecten met prijsinformatie.	false
`route`	string	De route waarop deze prijzen van toepassing zijn.	false
`countrycode`	string	De tweeletterige ISO-landcode waarop deze prijzen van toepassing zijn voor de betreffende route, indien van toepassing.	true
`countryname`	string	De Engelse landnaam die overeenkomt met de landcode, indien van toepassing.	true
`mccmnc`	string	De MCCMNC waarop deze prijzen van toepassing zijn voor de betreffende route, indien van toepassing. Heeft voorrang op prijzen op landniveau.	true
`cns`	string	Het kiesvoorvoegsel waarop deze prijzen van toepassing zijn voor de betreffende route, indien van toepassing. Heeft voorrang op prijzen op landniveau en MCCMNC-niveau.	true
`route_type`	string	Het bijbehorende routetype, d.w.z. `HLR`, `MNP`, `NT`.	false
`route_type`	string	De bijbehorende prijs in EUR.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/balancebeveiligd

Dit endpoint haalt uw huidige accountsaldo op, zodat u processen kunt automatiseren op basis van uw creditsaldo. Het werkt naadloos samen met de meldingen voor laag creditsaldo die u kunt configureren op uw betalingenpagina.

Verzoek Succesvolle Respons Foutrespons

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

{
    "balance":"1002.90"
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`balance`	string	Uw huidige accountsaldo in EUR. Een decimale waarde van het type string.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/pingopenbaar

Dit endpoint stuurt een ping-verzoek naar de API en biedt een eenvoudige methode om uw verbinding met de HLR Lookups API te testen.

Verzoek Succesvolle Respons Foutrespons

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

{
    "success":true
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`success`	boolean	Geeft aan dat het verzoek succesvol is verwerkt.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/timeopenbaar

Dit endpoint retourneert een Unix-timestamp die de huidige tijd op de HLR Lookups-server weergeeft. Gebruik dit om de klok van uw server te synchroniseren bij het genereren van de Digest-Auth-handtekening voor authenticatie, zodat eventuele verschillen tussen uw servertijd en de HLR Lookups-servertijd worden gecorrigeerd.

Verzoek Succesvolle Respons Foutrespons

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

{
    "time":1525898643
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`time`	integer	Unix-timestamp die de huidige HLR Lookups-servertijd weergeeft.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

GET/auth-testbeveiligd

Dit endpoint dient als initiële test voor uw Basic-Auth of, bij voorkeur, Digest-Auth implementatie.

Basic Auth Verzoek Digest Auth Verzoek Succesvolle Respons Foutrespons

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

Verzoek headers

Sleutel	Type	Omschrijving
`X-Basic`	string	SHA256-hash van `YOUR_API_KEY:YOUR_API_SECRET`. Neem het dubbele punt symbool (:) op in de hash.

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"

Verzoek headers

Sleutel	Type	Omschrijving
`X-Digest-Key`	string	Uw HLR Lookups API-sleutel
`X-Digest-Signature`	string	Unieke Digest-Auth handtekening (zie authenticatie)
`X-Digest-Timestamp`	integer	Huidige Unix timestamp (zie ook `GET /time`)

{
    "success":true
}

Succesvolle Respons Attributen

Naam	Type	Omschrijving	Nullable
`success`	boolean	Geeft aan dat het verzoek succesvol is verwerkt.	false

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

Foutrespons Parameters

Naam	Type	Omschrijving	Nullable
`errors[]`	string[]	Een lijst met strings die de fout uitleggen.	false

Scroll Omhoog

Legacy API Documentatie

Let op: de legacy API is verouderd en zal in de toekomst worden uitgefaseerd. We raden u ten zeerste aan om zo spoedig mogelijk te upgraden naar de nieuwste versie.

Als u onze HLR Lookups API tussen 2013 en begin 2020 heeft geïmplementeerd, gebruikt u onze legacy API. Raadpleeg in dat geval onze legacy API documentatie.

Legacy API Documentatie

API Documentatie

Aan de slag

HLR Lookups

MNP Lookups

NT Lookups

Routering

Prijzen

Tools

Aan de slag

De HLR Lookups API gebruiken

Voorbeeldverzoek

Voorbeeld Payload

Succesvolle Respons application/json

Aanvullende Lookup-diensten

Mobile Number Portability (MNP) Lookups

Number Type Detection (NT) Lookups

Software Development Kits (SDK's)

Tools

Geen ontwikkelaar?

Authenticatie

API-sleutel en API-geheim

HTTP Basic Auth

Aanbevolen: X-Basic Header met SHA256

Basic Auth Verzoek

Basic Authentication headers

Codevoorbeeld

Verzoekvoorbeeld

Verzoek headers

Samenstellen van de handtekening

Digest handtekening componenten

Codevoorbeelden

Concepten

Synchrone HLR Lookup API

Asynchrone HLR Lookup API

SDK's (Software Development Kits)

PHP SDK

NodeJS SDK

Ruby SDK

POST/hlr-lookupbeveiligd

Payload

Verzoekparameters

Succesvolle Respons Attributen

Foutrespons Parameters

POST/hlr-lookupsbeveiligd

Payload

Verzoekparameters

Succesvolle Respons Attributen

Foutrespons Parameters

Webhooks verwerken

Authenticatie

Codevoorbeeld

Ontvangst bevestigen

Webhook-payload

Webhook Payload Attributen

POST/mnp-lookupbeveiligd

Payload

Verzoekparameters

Succesvolle Respons Attributen

Foutrespons Parameters

POST/mnp-lookupsbeveiligd

Payload

Verzoekparameters

Succesvolle Respons Attributen

Foutrespons Parameters

Webhooks verwerken

Authenticatie

Codevoorbeeld

Ontvangst bevestigen

Webhook-payload

Webhook Payload Attributen

POST/nt-lookupbeveiligd

Payload

Verzoekparameters

Succesvolle Respons Attributen

Foutrespons Parameters

POST/nt-lookups beveiligd

Payload

Verzoekparameters

Succesvolle Respons Attributen

Foutrespons Parameters