DEPRECATION NOTICE
This API version is deprecated and scheduled for retirement in the future. We highly recommend to upgrade to the latest version at your earliest convenience.
Current API VersionAPI Access
Access the API via command line tools such as cURL or wget, any REST client, a browser window or any other way of sending an HTTP request. This API has been implemented as open source Software Development Kits for Ruby
, PHP
and NodeJS
.
Endpoint URL
Send all HTTP(S) requests to https://www.hlr-lookups.com/api
. Send requests securely by using HTTPS.
Authentication
Authenticate by specifying username
and password
as parameters in the HTTP(s) request. API authentication is possible using username and password for the web platform. However we recommend using the dedicated API username and password instead. This way your applications remain unaffected by web platform password changes. Your API username and password can be obtained in your API Settings.
Requests
Send requests via HTTP POST or GET. Submit parameters as query string (GET) or in the request body post fields (POST). Use POST or GET interchangeably.
GET https://www.hlr-lookups.com/api?action=getBalance&username=username&password=password
Response Object
Expect to see a 200 OK http status code and read the success
parameter from the JSON payload in the HTTP response body. If you see status code 50x something is wrong with the system. This should never happen but it is a good idea to account for it in your implementation. A status code of 502 or 504 is returned when you exceed the amount of permitted maximum concurrent connections or API requests in your account. When the response status is 200 OK you see see a JSON object in the HTTP response body. The success
attribute of the object indicates whether the request was processed correctly or not. Please examine the following examples.
JSON Response Structure for a Successful Request
200 OK { "success":true, "messages":[], "results":{ "balance":"295.23000" } }
-
success
Boolean
Indicates whether the request could be processed successfully. -
messages
Array
A list of message strings or empty. -
results
Array | Object
A list of results in key-value format or an object containing a result in key-value format. Different payload for eachaction
.
JSON Response Structure for a Failed Request
200 OK { "success":false, "errors":{ "fieldErrors":[], "globalErrors":[ "Authentication Failed." ] } }
-
success
Boolean
Indicates whether the request could be processed successfully. -
errors
Object
An object with lists of field specific or global errors. -
errors.fieldErrors
Array
A list of arrays with parameter specific errors, e.g.[["msisdn","The MSISDN seems to be invalid."],["route","Invalid route selection."]]
. The first value in each nested array identifies the erroneous parameter, the second value is the corresponding error message. -
errors.globalErrors
Array
A list of global errors as strings, e.g.["Authentication Failed"]
Actions
The API is used for different purposes by specifying an action parameter (e.g. submitSyncLookupRequest
). The HTTP request and response for each action are structured as described in the examples above and similar to implement. The required parameters and topology of the results are documented below for each particular action. Invoke actions by specifying an action
parameter in the HTTP request.
HLR Lookup Actions
Action | Description |
---|---|
submitSyncLookupRequest |
Synchronous HLR Lookup (most popular) |
submitAsyncLookupRequest |
Asynchronous HLR Lookups |
setAsyncCallbackUrl |
Asynchronous HLR Callback URL Setting |
Number Type Lookup Actions
Action | Description |
---|---|
submitSyncNumberTypeLookupRequest |
Synchronous Number Type Lookup |
submitAsyncNumberTypeLookupRequest |
Asynchronous Number Type Lookups |
setNtAsyncCallbackUrl |
Asynchronous Number Type Callback URL Setting |
Account and Service Monitoring
Action | Description |
---|---|
getBalance |
Account Balance Query |
doHealthCheck |
System Health Check |
submitSyncLookupRequest
Submits a synchronous HLR Lookup request. The HLR is queried in real time and results presented in the response body. Read more about the concept of synchronous HLR lookups.
curl 'https://www.hlr-lookups.com/api/?action=submitSyncLookupRequest&msisdn=+491788735000&route=IP1&storage=CURL-TEST&username=USERNAME&password=PASSWORD'
Request
POST/GET https://www.hlr-lookups.com/api action=submitSyncLookupRequest msisdn=string route=string storage=string username=string password=string
Params
-
action
String
submitSyncLookupRequest
-
msisdn
String
MSISDN in international format, e.g.+491780000000
. -
route (optional)
String Nullable
A routing assignment, e.g.IP1
. If no route is set the default route will be used. See available routes. -
storage (optional)
String Nullable
A storage assignment, e.g.RESULTS-FOR-SAMPLE-X
. If no storage is set the default storage for synchronous lookups (SYNC-API
) will be used. Read more about storages. -
username
String
Your username. -
password
String
Your password.
Response
200 OK { "success":true, "results":[ { "id":"6cc59cdc1988", "msisdncountrycode":"DE", "msisdn":"+491780000000", "statuscode":"HLRSTATUS_DELIVERED", "hlrerrorcodeid":null, "subscriberstatus":"SUBSCRIBERSTATUS_CONNECTED", "imsi":"000000000000000", "mccmnc":"26203", "mcc":"262", "mnc":"03", "msin":"0000000000", "servingmsc":"000000000000", "servinghlr":"000000000000", "originalnetworkname":"E-Plus", "originalcountryname":"Germany", "originalcountrycode":"DE", "originalcountryprefix":"+49", "originalnetworkprefix":"178", "roamingnetworkname":"T-Mobile", "roamingcountryname":"United States", "roamingcountrycode":"US", "roamingcountryprefix":"+1", "roamingnetworkprefix":"404455", "portednetworkname":null, "portedcountryname":null, "portedcountrycode":null, "portedcountryprefix":null, "portednetworkprefix":null, "isvalid":"Yes", "isroaming":"Yes", "isported":"No", "usercharge":"0.01", "inserttime":"2014-12-13 07:23:59.891+08", "storage":"SYNC-API", "route":"IP1", "interface":"Sync API" } ] }
Results
If success is true results contains a list of objects with lookup results. In the synchronous lookup response the list contains exactly one result.
-
id
String
A unique identifier for this lookup request. -
msisdncountrycode
String Nullable
The two-character ISO country code for the MSISDN. Null if the number is invalid. -
msisdn
String
The normalized MSISDN in international format. -
statuscode
String
The result status for this HLR Lookup request.HLR Status Meaning HLRSTATUS_QUEUED
The lookup is queued and pending execution. HLRSTATUS_PROCESSING
The lookup is processing. HLRSTATUS_DELIVERED
The lookup signal was succesfully delivered. HLRSTATUS_UNDELIVERED
The lookup signal could not be delivered. HLRSTATUS_UNKNOWN
The lookup status is unknown. HLRSTATUS_REJECTED
The MSISDN does not qualify for a lookup and has been rejected. HLRSTATUS_EXPIRED
The lookup has expired. HLRSTATUS_ERROR
The lookup could not be performed. -
hlrerrorcodeid
Integer Nullable
Can contain a numeric errorcode if the lookup signal could not be succesfully delivered. -
subscriberstatus
String
Indicates to connection status of the handset.Subscriber Status Meaning SUBSCRIBERSTATUS_CONNECTED
The MSISDN is valid and the subscriber is connected to a network. SUBSCRIBERSTATUS_ABSENT
The MSISDN is valid but the subscriber is not connected to a network. SUBSCRIBERSTATUS_UNKNOWN_MSISDN
The MSISDN is unknown in the network. SUBSCRIBERSTATUS_UNDETERMINED
The subscriber status could not be determined. SUBSCRIBERSTATUS_INVALID
The MSISDN is invalid. -
imsi
String Nullable
International Mobile Subscriber Identity (IMSI). Unique identification number associated with the handset SIM card. -
mccmnc
String Nullable
A combined representation of the Mobile Country Code (MCC) and the Mobile Network Code (MNC). -
mcc
String Nullable
The Mobile Country Code (MCC). -
mnc
String Nullable
The Mobile Network Code (MNC). -
msin
String Nullable
The Mobile Subscription Identification Number (MSIN) within the mobile network operator database. -
servingmsc
String Nullable
The Mobile Switching Center (MSC) catering to the MSISDN. -
servinghlr
String Nullable
The Home Location Register (HLR) catering to the MSISDN. -
originalnetworkname
String Nullable
The mobile network this MSISDN belongs to. If the MSISDN is ported then this is the network it originally belonged to. -
originalcountryname
String Nullable
The country name for the MSISDN. -
originalcountrycode
String Nullable
The two-character ISO country code for the MSISDN. -
originalcountryprefix
String Nullable
The mobile network prefix this MSISDN belongs to. If the MSISDN is ported then this is the network it originally belonged to. -
originalnetworkprefix
String Nullable
The nationally significant network prefix. -
roamingnetworkname:
String Nullable
The roaming mobile network operator name. -
roamingcountryname
String Nullable
The roaming country. -
roamingcountrycode
String Nullable
The two-character ISO country code of the roaming country. -
roamingcountryprefix
String Nullable
The international dialling prefix of the roaming country. -
roamingnetworkprefix
String Nullable
The nationally significant network prefix of the roaming network. -
portednetworkname
String Nullable
The ported network name. Indicates the network the MSISDN has been ported to. -
portedcountryname
String Nullable
The ported country name. -
portedcountrycode
String Nullable
The two-character ISO country code of the ported country. -
portedcountryprefix
String Nullable
The international dialling prefix of the ported country. -
isvalid
String
Indicates whether the MSISDN is syntactically valid. Contains "Yes" or "No". -
isroaming
String
Indicates whether the subscriber is roaming. Contains "Yes", "No" or null. -
isported
String
Indicates whether the MSISDN is ported. Contains "Yes" or "No". -
usercharge
String
Indicates the charge for this lookup in EUR. -
inserttime
String
Indicates the lookup timestamp. -
storage
String
Indicates the storage to which the result was saved. Read more about storages. -
route
String
Indicates the route used for this lookup. See available routes. -
interface
String
Indicates the interface used for this lookup, i.e.Sync API
orAsync API
.
Back to Index
submitAsyncLookupRequest
Submits asynchronous HLR Lookups containing up to 1,000 MSISDNs per request. Our server acknowledges the receipt of MSISDNs and sends results asynchronously via an HTTP POST request to a callback URL on your server. The callback URL can be defined by submitting an API request (setAsyncCallbackUrl) or by setting it in the API settings in your account. Read more about the concept of asynchronous HLR lookups.
curl 'https://www.hlr-lookups.com/api/?action=submitAsyncLookupRequest&msisdns=+491788735000,+491788735001&route=IP1&storage=CURL-TEST&username=USERNAME&password=PASSWORD'
Request
POST/GET https://www.hlr-lookups.com/api action=submitAsyncLookupRequest msisdns=string route=string storage=string username=string password=string
Params
-
action
String
submitAsyncLookupRequest
-
msisdns
String
A comma separated list of MSISDNs in international format, e.g.+491780000000,+491780000001
. Up to 1,000 per request. -
route (optional)
String Nullable
A routing assignment, e.g.IP1
. If no route is set the default route will be used. See available routes. -
storage (optional)
String Nullable
A storage assignment, e.g.RESULTS-FOR-SAMPLE-X
. If no storage is set the default storage for asynchronous lookups (ASYNC-API
) will be used. Read more about storages. -
username
String
Your username. -
password
String
Your password.
Response
200 OK { "success":true, "messages":[], "results":{ "acceptedMsisdns":[ { "id":"0424928f332e", "msisdn":"+491788735000" } ], "rejectedMsisdns":[], "acceptedMsisdnCount":1, "rejectedMsisdnCount":0, "totalCount":1, "charge":0.01, "storage":"ASYNC-API", "route":"IP1" } }
Results
A JSON object acknowledging the request, containing ids and indicating which MSISDNs were accepted for processing.
-
acceptedMsisdns
Array (of objects)
A list of key-value pair objects containing an id for every submitted MSISDN. The values for id and msisdn are of type string. -
rejectedMsisdns
Array (of objects)
A list of key-value pair objects containing rejected MSISDNs. The value for id is null. The value for msisdn is of type string. -
acceptedMsisdnCount
Integer
The total number of accepted MSISDNs. -
rejectedMsisdnCount
Integer
The total number of rejected MSISDNs. -
totalCount
Integer
The total number of submitted MSISDNs. -
charge
Decimal
The total charge for this request in EUR. -
storage
String
Indicates the storage to which the results will be saved. Read more about storages. -
route
String
Indicates the route used for this request. See available routes.
Callbacks
Results are posted asynchronously to a callback URL on your server by issuing HTTP POST requests with one parameter json. Please note that one callback can contain up to 1,000 results. The callback client expects to see a HTTP response code "200 OK" from your server. If a different response code is returned, a timeout (30 seconds) or some other error occurs, the callback client will re-attempt to send the results after a minute again. If it still encounters an error will continue do re-attempt the request after 2, 4, 8, 16, 32, 64, 128, 256, 512 and for a last time after 1024 minutes.
POST https://callback-url-on-your-server json={ "success":true, "results":[ { "id":"6cc59cdc1988", "msisdncountrycode":"DE", "msisdn":"+491780000000", "statuscode":"HLRSTATUS_DELIVERED", "hlrerrorcodeid":null, "subscriberstatus":"SUBSCRIBERSTATUS_CONNECTED", "imsi":"000000000000000", "mccmnc":"26203", "mcc":"262", "mnc":"03", "msin":"0000000000", "servingmsc":"000000000000", "servinghlr":"000000000000", "originalnetworkname":"E-Plus", "originalcountryname":"Germany", "originalcountrycode":"DE", "originalcountryprefix":"+49", "originalnetworkprefix":"178", "roamingnetworkname":"T-Mobile", "roamingcountryname":"United States", "roamingcountrycode":"US", "roamingcountryprefix":"+1", "roamingnetworkprefix":"404455", "portednetworkname":null, "portedcountryname":null, "portedcountrycode":null, "portedcountryprefix":null, "portednetworkprefix":null, "isvalid":"Yes", "isroaming":"Yes", "isported":"No", "usercharge":"0.01", "inserttime":"2014-12-13 07:23:59.891+08", "storage":"SYNC-API", "route":"IP1", "interface":"Async API" } ] }
Results
Results are presented as a list of objects containing results for individual MSISDNs.
-
id
String
A unique identifier for this lookup request. -
msisdncountrycode
String Nullable
The two-character ISO country code for the MSISDN. Null if the number is invalid. -
msisdn
String
The normalized MSISDN in international format. -
statuscode
String
The result status for this HLR Lookup request.HLR Status Meaning HLRSTATUS_QUEUED
The lookup is queued and pending execution. HLRSTATUS_PROCESSING
The lookup is processing. HLRSTATUS_DELIVERED
The lookup signal was succesfully delivered. HLRSTATUS_UNDELIVERED
The lookup signal could not be delivered. HLRSTATUS_UNKNOWN
The lookup status is unknown. HLRSTATUS_REJECTED
The MSISDN does not qualify for a lookup and has been rejected. HLRSTATUS_EXPIRED
The lookup has expired. HLRSTATUS_ERROR
The lookup could not be performed. -
hlrerrorcodeid
Integer Nullable
Can contain a numeric errorcode if the lookup signal could not be succesfully delivered. -
subscriberstatus
String
Indicates to connection status of the handset.Subscriber Status Meaning SUBSCRIBERSTATUS_CONNECTED
The MSISDN is valid and the subscriber is connected to a network. SUBSCRIBERSTATUS_ABSENT
The MSISDN is valid but the subscriber is not connected to a network. SUBSCRIBERSTATUS_UNKNOWN_MSISDN
The MSISDN is unknown in the network. SUBSCRIBERSTATUS_UNDETERMINED
The subscriber status could not be determined. SUBSCRIBERSTATUS_INVALID
The MSISDN is invalid. -
imsi
String Nullable
International Mobile Subscriber Identity (IMSI). Unique identification number associated with the handset SIM card. -
mccmnc
String Nullable
A combined representation of the Mobile Country Code (MCC) and the Mobile Network Code (MNC). -
mcc
String Nullable
The Mobile Country Code (MCC). -
mnc
String Nullable
The Mobile Network Code (MNC). -
msin
String Nullable
The Mobile Subscription Identification Number (MSIN) within the mobile network operator database. -
servingmsc
String Nullable
The Mobile Switching Center (MSC) catering to the MSISDN. -
servinghlr
String Nullable
The Home Location Register (HLR) catering to the MSISDN. -
originalnetworkname
String Nullable
The mobile network this MSISDN belongs to. If the MSISDN is ported then this is the network it originally belonged to. -
originalcountryname
String Nullable
The country name for the MSISDN. -
originalcountrycode
String Nullable
The two-character ISO country code for the MSISDN. -
originalcountryprefix
String Nullable
The mobile network prefix this MSISDN belongs to. If the MSISDN is ported then this is the network it originally belonged to. -
originalnetworkprefix
String Nullable
The nationally significant network prefix. -
roamingnetworkname:
String Nullable
The roaming mobile network operator name. -
roamingcountryname
String Nullable
The roaming country. -
roamingcountrycode
String Nullable
The two-character ISO country code of the roaming country. -
roamingcountryprefix
String Nullable
The international dialling prefix of the roaming country. -
roamingnetworkprefix
String Nullable
The nationally significant network prefix of the roaming network. -
portednetworkname
String Nullable
The ported network name. Indicates the network the MSISDN has been ported to. -
portedcountryname
String Nullable
The ported country name. -
portedcountrycode
String Nullable
The two-character ISO country code of the ported country. -
portedcountryprefix
String Nullable
The international dialling prefix of the ported country. -
isvalid
String
Indicates whether the MSISDN is syntactically valid. Contains "Yes" or "No". -
isroaming
String
Indicates whether the subscriber is roaming. Contains "Yes", "No" or null. -
isported
String
Indicates whether the MSISDN is ported. Contains "Yes" or "No". -
usercharge
String
Indicates the charge for this lookup in EUR. -
inserttime
String
Indicates the lookup timestamp. -
storage
String
Indicates the storage to which the result was saved. Read more about storages. -
route
String
Indicates the route used for this lookup. See available routes. -
interface
String
Indicates the interface used for this lookup, i.e.Sync API
orAsync API
.
Back to Index
setAsyncCallbackUrl
Sets the callback URL for asynchronous HLR lookups. Read more about the concept of asynchronous HLR lookups.
curl 'https://www.hlr-lookups.com/api/?action=setAsyncCallbackUrl&url=http://user:pass@www.your-server.com/path/file&username=USERNAME&password=PASSWORD'
Request
POST/GET https://www.hlr-lookups.com/api action=setAsyncCallbackUrl url=string username=string password=string
Params
-
action
String
setAsyncCallbackUrl
-
url
String
A url in the format ofhttp://user:pass@www.your-server.com/path/file
. Basic-Auth user and password are optional. SSL is supported by using thehttps
scheme. -
username
String
Your username. -
password
String
Your password.
Response
200 OK { "success":true, "messages":[], "results":{ "url":"http://user:pass@www.your-server.com/path/file" } }
Back to Index
submitSyncNumberTypeLookupRequest
Submits a synchronous number type lookup request. Determines whether a given number is valid and whether it belongs to a landline, mobile, VoIP, pager or other numbering plan range.
curl 'https://www.hlr-lookups.com/api/?action=submitSyncNumberTypeLookupRequest&msisdn=+4989702626&route=LC1&storage=CURL-TEST&username=USERNAME&password=PASSWORD'
Request
POST/GET https://www.hlr-lookups.com/api action=submitSyncNumberTypeLookupRequest number=string route=string storage=string username=string password=string
Params
-
action
String
submitSyncNumberTypeLookupRequest -
number
String
Phone number in international format, e.g.+4989702626
. -
route (optional)
String Nullable
A routing assignment, e.g.LC1
. If no route is set the default route will be used. See available routes. -
storage (optional)
String Nullable
A storage assignment, e.g.RESULTS-FOR-SAMPLE-X
. If no storage is set the default storage for synchronous lookups (SYNC-API-NT
) will be used. Read more about storages. -
username
String
Your username. -
password
String
Your password.
Response
200 OK { "success":true, "results":[ { "id":"2ed0788379c6", "number":"+4989702626", "numbertype":"LANDLINE", "state":"COMPLETED", "isvalid":"Yes", "invalidreason":null, "ispossiblyported":"No", "isvanitynumber":"No", "qualifiesforhlrlookup":"No", "originalcarrier":null, "mccmnc":null, "mcc":null, "mnc":null, "countrycode":"DE", "regions":[ "Munich" ], "timezones":[ "Europe\/Berlin" ], "infotext":"This is a landline number.", "usercharge":"0.0050", "inserttime":"2015-12-04 10:36:41.866283+00", "storage":"SYNC-API-NT-2015-12", "route":"LC1", "interface":"Sync API" } ] }
Results
If success is true results contains a list of objects with lookup results. In the synchronous lookup response the list contains exactly one result.
-
id
String
A unique identifier for this lookup request. -
number
String
The normalized phone number in international format. -
numbertype
String
The detected number type, e.g. LANDLINE or MOBILE.Number Type Description LANDLINE
Landline phone number. MOBILE
Mobile phone number. Qualifies for HLR lookup to obtain additional connection status, network, portability and roaming information. MOBILE_OR_LANDLINE
Landline or mobile phone number. Might qualify for HLR lookup (e.g. US and Canada) TOLL_FREE
Toll free phone number. PREMIUM_RATE
Premium rate phone number with additional charges SHARED_COST
Shared cost phone number. Typically less expensive than premium rate phone numbers VOIP
Voice over IP phone number. Includes TSoIP phone numbers (Telephony Service over IP) PAGER
Pager phone number. Typically no voice functionality. UAN
Univeral Access Number (Company Number). Might be routed to specific offices but allows one number to be used for the company. VOICEMAIL
Voicemail phone number. UNKNOWN
Unknown phone number. Phone number cannot be mapped or is invalid. -
state
String
The lookup state, e.g. COMPLETED or FAILED.State Description QUEUED
The lookup is currently queued and pending execution. PROCESSING
The lookup is being processed. COMPLETED
The lookup is complete. FAILED
The lookup failed. -
isvalid
String Nullable
Indicates whether the phone number is valid. Contains "Yes" or "No". This does not determine whether the number is connected, which is impossible for landlines and static lookups. If this is a mobile number the connectivity status can be obtained by submitting an HLR lookup. -
invalidreason
String Nullable
Contains a human readable reason if the number is invalid, e.g. "Too short" or "Invalid country code". -
isvanitynumber
String Nullable
Indicates whether the phone number is a vanity number (has alphabetic characters). Contains "Yes" or "No". -
qualifiesforhlrlookup
String Nullable
Indicates whether the number qualifies for further analysis with an HLR lookup. Contains "Yes" or "No". -
originalcarrier
String Nullable
The original carrier for this number. Does not take into account possible portability for mobile numbers. Portability and roaming statuses can be obtained by performing an HLR lookup. -
mccmnc
String Nullable
A combined representation of the Mobile Country Code (MCC) and the Mobile Network Code (MNC). -
mcc
String Nullable
The Mobile Country Code (MCC). -
mnc
String Nullable
The Mobile Network Code (MNC). -
countrycode
String(2) Nullable
The two character ISO country code associated with this phone number. -
regions
Array(String) Nullable
A list of human readable text representations of the geographic region(s) associated with this number. -
timezones
Array(String) Nullable
A list of timezones associated with this number (in Olson format). -
infotext
String Nullable
A human readable text with context information and details on the lookup results. -
usercharge
String
Indicates the charge for this lookup in EUR. -
inserttime
String
Indicates the lookup timestamp. -
storage
String
Indicates the storage to which the result was saved. Read more about storages. -
route
String
Indicates the route used for this lookup. See available routes. -
interface
String
Indicates the interface used for this lookup.
Back to Index
submitAsyncNumberTypeLookupRequest
Submits an asynchronous number type lookup with up to 1,000 MSISDNs per request. Our server acknowledges the receipt of the numbers and sends results asynchronously via an HTTP POST request to a callback URL on your server. The callback URL can be defined by submitting an API request (setNtAsyncCallbackUrl) or by setting it in the API settings in your account.
curl 'https://www.hlr-lookups.com/api/?action=submitAsyncNumberTypeLookupRequest&numbers=+4989702626,+491788735000&route=LC1&storage=CURL-TEST&username=USERNAME&password=PASSWORD'
Request
POST/GET https://www.hlr-lookups.com/api action=submitAsyncNumberTypeLookupRequest numbers=string route=string storage=string username=string password=string
Params
-
action
String
submitAsyncNumberTypeLookupRequest
-
numbers
String
A comma separated list of phone numbers in international format, e.g.+4989702626,+491788735000
. -
route (optional)
String Nullable
A routing assignment, e.g.LC1
. If no route is set the default route will be used. See available routes. -
storage (optional)
String Nullable
A storage assignment, e.g.RESULTS-FOR-SAMPLE-X
. If no storage is set the default storage for synchronous lookups (SYNC-API-NT
) will be used. Read more about storages. -
username
String
Your username. -
password
String
Your password.
Response
200 OK { "success":true, "messages":[], "results":{ "acceptedNumbers":[ { "id":"f09b30014d5e", "number":"+4989702626" }, { "id":"364c0ad33c02", "number":"+491788735000" } ], "rejectedNumbers":[ { "id":null, "number":"asdf" } ], "acceptedNumberCount":2, "rejectedNumberCount":1, "totalCount":3, "charge":0.01, "storage":"ASYNC-API-NT-2015-12", "route":"LC1" } }
Results
A JSON object acknowledging the request, containing ids and indicating which MSISDNs were accepted for processing.
-
acceptedNumbers
Array (of objects)
A list of key-value pair objects containing an id for every submitted number. The values for id and number are of type string. -
rejectedNumbers
Array (of objects)
A list of key-value pair objects containing rejected numbers. The value for id is null. The value for number is of type string. -
acceptedNumberCount
Integer
The total number of accepted numbers. -
rejectedNumberCount
Integer
The total number of rejected numbers. -
totalCount
Integer
The total number of submitted numbers. -
charge
Decimal
The total charge for this request in EUR. -
storage
String
Indicates the storage to which the results will be saved. Read more about storages. -
route
String
Indicates the route used for this request. See available routes.
Callbacks
Results are posted asynchronously to a callback URL on your server by issuing HTTP POST requests with one parameter json. Please note that one callback can contain up to 100 results.
POST https://callback-url-on-your-server json={ "success":true, "results":[ { "id":"2ed0788379c6", "number":"+4989702626", "numbertype":"LANDLINE", "state":"COMPLETED", "isvalid":"Yes", "ispossiblyported":"No", "isvanitynumber":"No", "qualifiesforhlrlookup":"No", "originalcarrier":null, "mccmnc":null, "mcc":null, "mnc":null, "countrycode":"DE", "regions":[ "Munich" ], "timezones":[ "Europe\/Berlin" ], "infotext":"This is a landline number.", "usercharge":"0.0050", "inserttime":"2015-12-04 10:36:41.866283+00", "storage":"SYNC-API-NT-2015-12", "route":"LC1", "interface":"Async API" }, { "id":"282b6c3b003d", "number":"+491788735000", "numbertype":"MOBILE", "state":"COMPLETED", "isvalid":"Yes", "ispossiblyported":"Yes", "isvanitynumber":"No", "qualifiesforhlrlookup":"Yes", "originalcarrier":"Eplus", "countrycode":"DE", "mcc":null, "mnc":null, "mccmnc":null, "regions":[ "Germany" ], "timezones":[ "Europe\/Berlin" ], "infotext":"This number qualifies for HLR lookups. This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup. MCCMNC information could not be obtained. Please submit an HLR lookup to acquire it.", "usercharge":"0.0050", "inserttime":"2015-12-04 10:36:41.866283+00", "storage":"SYNC-API-NT-2015-12", "route":"LC1", "interface":"Async API" } ] }
Results
Results are presented as a list of objects containing results for individual numbers.
-
id
String
A unique identifier for this lookup request. -
number
String
The normalized phone number in international format. -
numbertype
String
The detected number type, e.g. LANDLINE or MOBILE.Number Type Description LANDLINE
Landline phone number. MOBILE
Mobile phone number. Qualifies for HLR lookup to obtain additional connection status, network, portability and roaming information. MOBILE_OR_LANDLINE
Landline or mobile phone number. Might qualify for HLR lookup (e.g. US and Canada) TOLL_FREE
Toll free phone number. PREMIUM_RATE
Premium rate phone number with additional charges SHARED_COST
Shared cost phone number. Typically less expensive than premium rate phone numbers VOIP
Voice over IP phone number. Includes TSoIP phone numbers (Telephony Service over IP) PAGER
Pager phone number. Typically no voice functionality. UAN
Univeral Access Number (Company Number). Might be routed to specific offices but allows one number to be used for the company. VOICEMAIL
Voicemail phone number. UNKNOWN
Unknown phone number. Phone number cannot be mapped or is invalid. -
state
String
The lookup state, e.g. COMPLETED or FAILED.State Description QUEUED
The lookup is currently queued and pending execution. PROCESSING
The lookup is being processed. COMPLETED
The lookup is complete. FAILED
The lookup failed. -
isvalid
String Nullable
Indicates whether the phone number is valid. Contains "Yes" or "No". This does not determine whether the number is connected, which is impossible for landlines and static lookups. If this is a mobile number the connectivity status can be obtained by submitting an HLR lookup. -
invalidreason
String Nullable
Contains a human readable reason if the number is invalid, e.g. "Too short" or "Invalid country code". -
isvanitynumber
String Nullable
Indicates whether the phone number is a vanity number (has alphabetic characters). Contains "Yes" or "No". -
qualifiesforhlrlookup
String Nullable
Indicates whether the number qualifies for further analysis with an HLR lookup. Contains "Yes" or "No". -
originalcarrier
String Nullable
The original carrier for this number. Does not take into account possible portability for mobile numbers. Portability and roaming statuses can be obtained by performing an HLR lookup. -
mccmnc
String Nullable
A combined representation of the Mobile Country Code (MCC) and the Mobile Network Code (MNC). -
mcc
String Nullable
The Mobile Country Code (MCC). -
mnc
String Nullable
The Mobile Network Code (MNC). -
countrycode
String(2) Nullable
The two character ISO country code associated with this phone number. -
regions
Array(String) Nullable
A list of human readable text representations of the geographic region(s) associated with this number. -
timezones
Array(String) Nullable
A list of timezones associated with this number (in Olson format). -
infotext
String Nullable
A human readable text with context information and details on the lookup results. -
usercharge
String
Indicates the charge for this lookup in EUR. -
inserttime
String
Indicates the lookup timestamp. -
storage
String
Indicates the storage to which the result was saved. Read more about storages. -
route
String
Indicates the route used for this lookup. See available routes. -
interface
String
Indicates the interface used for this lookup.
Back to Index
setNtAsyncCallbackUrl
Sets the callback URL for asynchronous number type lookups. Read more about the concept of asynchronous HLR lookups.
curl 'https://www.hlr-lookups.com/api/?action=setNtAsyncCallbackUrl&url=http://user:pass@www.your-server.com/path/file&username=USERNAME&password=PASSWORD'
Request
POST/GET https://www.hlr-lookups.com/api action=setNtAsyncCallbackUrl url=string username=string password=string
Params
-
action
String
setNtAsyncCallbackUrl
-
url
String
A url in the format ofhttp://user:pass@www.your-server.com/path/file
. Basic-Auth user and password are optional. SSL is supported by using thehttps
scheme. -
username
String
Your username. -
password
String
Your password.
Response
200 OK { "success":true, "messages":[], "results":{ "url":"http://user:pass@www.your-server.com/path/file" } }
Back to Index
getBalance
Returns the remaining balance (EUR) in your account.
curl 'https://www.hlr-lookups.com/api/?action=getBalance&username=USERNAME&password=PASSWORD'
Request
POST/GET https://www.hlr-lookups.com/api action=getBalance username=string password=string
Params
-
action
String
getBalance
-
username
String
Your username. -
password
String
Your password.
Response
200 OK { "success":true, "messages":[], "results":{ "balance":"295.23000" } }
Back to Index
doHealthCheck
Performs a health check on the system status, the user account and availability of each route. Should return an HTTP status code "200 OK". If a different status code is encountered, e.g. 500, you can assume that the health check has failed.
curl 'https://www.hlr-lookups.com/api/?action=doHealthCheck&username=USERNAME&password=PASSWORD'
Request
POST/GET https://www.hlr-lookups.com/api action=doHealthCheck username=string password=string
Params
-
action
String
doHealthCheck
-
username
String
Your username. -
password
String
Your password.
Response
200 OK { "success":true, "results":{ "system":{ "state":"up" }, "routes":{ "states":{ "IP1":"up", "ST2":"up", "SV3":"up", "IP4":"up", "XT5":"up", "XT6":"up", "NT7":"up", "LC1":"up" } }, "account":{ "lookupsPermitted":true, "balance":"295.23000" } } }
Results
A JSON object containing information about the general system status, the user account and availability of each route.
-
system.state
String
Returns up when the system is healthy or down when the system is not available. -
routes.states
Object
Contains the availability status for each route (read more about routes). Returns up when the route is available or down if it is not available. -
account.lookupsPermitted
Boolean
Indicates whether lookups can be invoked by the authenticated user. Should always return true. In case of false please contact your account manager. -
account.balance
Decimal (as String)
Returns the remaining balance of the authenticated user.
Back to Index