REST API Docs (Deprecated)

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 Version

API 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 each action.

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 StatusMeaning
    HLRSTATUS_QUEUEDThe lookup is queued and pending execution.
    HLRSTATUS_PROCESSINGThe lookup is processing.
    HLRSTATUS_DELIVEREDThe lookup signal was succesfully delivered.
    HLRSTATUS_UNDELIVEREDThe lookup signal could not be delivered.
    HLRSTATUS_UNKNOWNThe lookup status is unknown.
    HLRSTATUS_REJECTEDThe MSISDN does not qualify for a lookup and has been rejected.
    HLRSTATUS_EXPIREDThe lookup has expired.
    HLRSTATUS_ERRORThe 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 StatusMeaning
    SUBSCRIBERSTATUS_CONNECTEDThe MSISDN is valid and the subscriber is connected to a network.
    SUBSCRIBERSTATUS_ABSENTThe MSISDN is valid but the subscriber is not connected to a network.
    SUBSCRIBERSTATUS_UNKNOWN_MSISDNThe MSISDN is unknown in the network.
    SUBSCRIBERSTATUS_UNDETERMINEDThe subscriber status could not be determined.
    SUBSCRIBERSTATUS_INVALIDThe 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 or Async 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 StatusMeaning
    HLRSTATUS_QUEUEDThe lookup is queued and pending execution.
    HLRSTATUS_PROCESSINGThe lookup is processing.
    HLRSTATUS_DELIVEREDThe lookup signal was succesfully delivered.
    HLRSTATUS_UNDELIVEREDThe lookup signal could not be delivered.
    HLRSTATUS_UNKNOWNThe lookup status is unknown.
    HLRSTATUS_REJECTEDThe MSISDN does not qualify for a lookup and has been rejected.
    HLRSTATUS_EXPIREDThe lookup has expired.
    HLRSTATUS_ERRORThe 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 StatusMeaning
    SUBSCRIBERSTATUS_CONNECTEDThe MSISDN is valid and the subscriber is connected to a network.
    SUBSCRIBERSTATUS_ABSENTThe MSISDN is valid but the subscriber is not connected to a network.
    SUBSCRIBERSTATUS_UNKNOWN_MSISDNThe MSISDN is unknown in the network.
    SUBSCRIBERSTATUS_UNDETERMINEDThe subscriber status could not be determined.
    SUBSCRIBERSTATUS_INVALIDThe 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 or Async 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 of http://user:pass@www.your-server.com/path/file. Basic-Auth user and password are optional. SSL is supported by using the https 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 TypeDescription
    LANDLINELandline phone number.
    MOBILEMobile phone number. Qualifies for HLR lookup to obtain additional connection status, network, portability and roaming information.
    MOBILE_OR_LANDLINELandline or mobile phone number. Might qualify for HLR lookup (e.g. US and Canada)
    TOLL_FREEToll free phone number.
    PREMIUM_RATEPremium rate phone number with additional charges
    SHARED_COSTShared cost phone number. Typically less expensive than premium rate phone numbers
    VOIPVoice over IP phone number. Includes TSoIP phone numbers (Telephony Service over IP)
    PAGERPager phone number. Typically no voice functionality.
    UANUniveral Access Number (Company Number). Might be routed to specific offices but allows one number to be used for the company.
    VOICEMAILVoicemail phone number.
    UNKNOWNUnknown phone number. Phone number cannot be mapped or is invalid.
  • state
    String
    The lookup state, e.g. COMPLETED or FAILED.
    StateDescription
    QUEUEDThe lookup is currently queued and pending execution.
    PROCESSINGThe lookup is being processed.
    COMPLETEDThe lookup is complete.
    FAILEDThe 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 TypeDescription
    LANDLINELandline phone number.
    MOBILEMobile phone number. Qualifies for HLR lookup to obtain additional connection status, network, portability and roaming information.
    MOBILE_OR_LANDLINELandline or mobile phone number. Might qualify for HLR lookup (e.g. US and Canada)
    TOLL_FREEToll free phone number.
    PREMIUM_RATEPremium rate phone number with additional charges
    SHARED_COSTShared cost phone number. Typically less expensive than premium rate phone numbers
    VOIPVoice over IP phone number. Includes TSoIP phone numbers (Telephony Service over IP)
    PAGERPager phone number. Typically no voice functionality.
    UANUniveral Access Number (Company Number). Might be routed to specific offices but allows one number to be used for the company.
    VOICEMAILVoicemail phone number.
    UNKNOWNUnknown phone number. Phone number cannot be mapped or is invalid.
  • state
    String
    The lookup state, e.g. COMPLETED or FAILED.
    StateDescription
    QUEUEDThe lookup is currently queued and pending execution.
    PROCESSINGThe lookup is being processed.
    COMPLETEDThe lookup is complete.
    FAILEDThe 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 of http://user:pass@www.your-server.com/path/file. Basic-Auth user and password are optional. SSL is supported by using the https 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
© Velocity Made Good Ltd. 2015-2025 · Terms of Service · Privacy Policy · Data Processing Agreement https://www.hlr-lookups.com

© Velocity Made Good Ltd.