Realtime number information lookup (Messaging:NumberLookup) - Sales-LV/traffic-api GitHub Wiki

This operation lets you retrieve realtime information about a telephone number. Note that this is a synchronous realtime operation during which a request is made to the mobile network to retrieve the data. The request can take a few seconds so we suggest limiting the number of parallel requests and setting longer timeouts for these requests.

The information that you can retrieve is:

  • current subscriber status, e.g. whether the phone is available to the network, switched off, not assigned to any subscriber, etc.;
  • the current network the number belongs to;
  • if the number is currently roaming in a foreign network;
  • the network it is roaming in;
  • if the number was ported from its original network;
  • the original network it belonged to;
  • the network it was ported to.

Request parameters:

  • Number: Telephone number to check. It should include the country code, otherwise the system will assume it is the default country code that's set up for your account.

Response parameters:

  • OK (boolean): Indicates operation status, true for successful lookup, false otherwise;
  • Error (int): Error identifier, this will contain the reasons for unreachable numbers;
  • ErrorCode (string): Error code;
  • ErrorDescription (string): Human readable error description
  • Ported (boolean): Indicates if the number is ported from its original network
  • Roaming (boolean): Indicates if the number is currently roaming in a foreign network
  • MCCMNC (string): Mobile country code and mobile network code combination. (Note that the mobile country code is not the same as the country code that's used as a prefix when actually using the number.)
  • MCC (int): Mobile country code
  • MNC (int): Mobile network code. These codes aren't unique and are repeated among countries.
  • CC (int): Country code
  • Number (int): Checked telephone number without the country code prefix
  • CurrentNetwork (Network object): Data about the network the number currently belongs to. If the number is currently roaming, this will not be the roaming network but instead it will be the number's home network.
  • RoamingNetwork (Network object): Data about the roaming network, if the number is in roaming
  • PortedNetwork (Network object): Data about the network the number was ported to, if it was ported from its original network (if it was ported, this should usually be the same as CurrentNetwork)
  • OriginalNetwork (Network object): Data about the network the number was originally assigned to.

Note that there is no guarantee that any or most of the network data fields will be filled. The network data objects (CurrentNetwork, RoamingNetwork, PortedNetwork, OriginalNetwork) will have these parameters but it's possible that they any or some of them might be empty, depending on the networks and number status:

  • CC (int): Country code of the network (not the number)
  • MCC (int): Mobile country code of the network
  • MNC (int): Mobile network code of the network
  • NetworkName (string): Human readable name of the network
  • NetworkCode (string): Textual code describing the network. If set, this will be unique among all networks of all countries.
  • CountryName (string): Name of the country the network belongs to.

The network will have a different country code, mobile country code and mobile network code than the number in case of roaming.

Possible errors

These error codes are possible in addition to generic request errors in case of malformed request:

ERROR_OK (0): No error, the number is switched on and reachable.
ERROR_NO_NUMBER (1001): No number was provided to look up.
ERROR_INVALID_NUMBER (1002): An invalid number was provided (impossible number format for the given country code and number combination.
ERROR_UNKNOWN_SUBSCRIBER (1003): The operator doesn't have a subscriber for the provided number - this could happen if the number is assigned to the operator but the operator hasn't given number to any of its users.
ERROR_ABSENT_SUBSCRIBER (1004): The subscriber is currently not present in the operator's network. This can happen if the subscriber's phone is switched off or out of network coverage.
ERROR_UNKNOWN_EQUIPMENT (1005): The mobile device has not been recognized by the mobile operator.
ERROR_ROAMING_NOT_ALLOWED (1006): Subscriber is attempting to use another operator's infrastructure, however, the subscriber's home network and the roaming network do not have a roaming agreement, and it cannot be guaranteed that any call or messaging attempts will go through.
ERROR_ILLEGAL_SUBSCRIBER (1007): Subscriber is not allowed to use the network they're attempting to use.
ERROR_SERVICE_NOT_PROVISIONED (1008): The operator is currently not providing service to the subscriber. This could be due to temporarily cancelled agreements, low pre-paid account balance, unpaid bills, etc.
ERROR_ILLEGAL_EQUIPMENT (1009): The subscriber's device is not permitted in the mobile network.
ERROR_CALL_BARRED (1010): The subscriber has opted not to receive messages or calls to their number.
ERROR_FACILITY_NOT_SUPPORTED (1011): Facility not supported.
ERROR_NO_RESPONSE (1012): No response was received from the mobile network.

This list can have additional entries added to it in the future.

Example

Request:

{
    'Number': XXXXXXXXXXX
}

Response:

{
    "OK": true,
    "Error": 0,
    "ErrorCode": "ERROR_OK",
    "Ported": true,
    "Roaming": false,
    "CC": 371,
    "Number": 20000000,
    "MCCMNC": "24702",
    "MCC": 247,
    "MNC": 2,
    "CurrentNetwork": {
        "CC": 371,
        "MCC": 247,
        "MNC": 2,
        "NetworkName": "Tele2 Latvia",
        "NetworkCode": "TELE2LV",
        "CountryName":"Latvia"
    },
    "RoamingNetwork": {
        "CC": 370,
        "MCC": 246,
        "MNC": 3,
        "NetworkName": "TELE2",
        "NetworkCode": "",
        "CountryName":"Lithuania"
    },
    "PortedNetwork": {
        "CC":"371",
        "MCC":0,
        "MNC":0,
        "NetworkName":"TELE2",
        "NetworkCode":"",
        "CountryName":"Latvia"
    },
    "OriginalNetwork": {
        "CC":"371",
        "MCC":0,
        "MNC":0,
        "NetworkName":"LMT GSM (Latvijas Mobilais Telefons)",
        "NetworkCode":"",
        "CountryName":"Latvia"
    }
}