Skip to main content


Easy to understand tutorials made for you, by us.


How to send a Number Lookup

With our Number Lookup service you can get information about mobile numbers like is it a valid number, is the number still active, is the number ported or is the number roaming. In this tutorial we will explain how you can send a Number Lookup.Sending a Number Lookup is simple:

$numberLookup = $client->createNumberLookup('65123456789');
echo $numberLookup->getMessageId();

Mobile number

In order to perform a Number Lookup you will need the mobile number. The mobile number must always be in international format, without leading `+` or `00`. In international format means that you have add the country prefix to the local number. For example, if the country prefix is `+31` and the local number is `0612345678`, you remove the leading `0` of the local number and prepend the country prefix. As you then have to strip the leading `+` or `00`, the result will be `31612345678`.

Number Lookup result

Now our platform will perform the number lookup. To get the status of a number lookup, there a few options. You can simply get the status of the number lookup by the id when submitting the number lookup, poll for number lookups results or receive a HTTP call from our system. More information on that you can find in our API documentation. For this tutorial we will simply get the status based on the id.

Example to get the status of a number lookup:

$result = $client->getNumberLookup($numberLookup->getMessageId());

Example of the data returned by the API:

"applicationTag": "Default application",
"callbackUrl": null,
"countryCode": "nl",
"createdDateTime": "2019-01-30T11:34:04+00:00",
"imsi": "20412002",
"isPorted": "Yes",
"isRoaming": "Unknown",
"messageId": "eu-01-2.3754.nrl5c518bac56dd21.04206976",
"msc": "0",
"networkCode": 20412,
"number": "31624123456",
"operator": "(NETHERLANDS)KPN",
"reasonCode": 0,
"resultTimestamp": "2019-01-30T11:34:08+00:00",
"resultType": 0,
"salesPrice": 0.012,
"salesPriceCurrencyCode": "eur",
"status": "delivered",
"statusCode": 1,
"tag": "test",
"validity": 259200,
"validUntilDateTime": "2019-02-02T11:34:04+00:00",
"_links": {
"self": {
"href": ""

So what can we do with the returned information?

With the information returned by the API you can do several things:

  1. When the `status` is `delivered` it means the number is a valid number and still active.
  2. By the `countryCode` field you can see in which country the mobile number is registered in. This is a two-digit ISO country code.
  3. The `operator` field gives the name of the actual operator the mobile number is subscribed to.
  4. The `isPorted` field shows information if the number is ported or not. Ported means that the subscriber change from operator and took his mobile number with him. It depends on the country if mobile numbers can be ported or not.
  5. The `isRoaming` field show information if the number is currently not in his home country. For example when someone is on holiday or on a business trip.

When the status of the number lookup is `delivered`, the `countryCode` and `operator` are always set. The `isPorted` and `isRoaming` might not be set. This depends if there is enough information returned by the operators for the API to detect this.