Skip to main content

Lookup Phone Numbers and IP Addresses

CarrierX allows you to query information about phone numbers and IP addresses. You can find out the country of the phone number or IP address origin, their state (for US-based numbers and addresses), and some other information.

Phone Number Lookup​

Basic phone number lookup requests return information about the number region and the way the requested number looks in various formats. If you have additional scopes enabled for your account, you can query for extra information.

Phone Number Lookup Request​

To query information about a phone number, send the following API request:

curl -X GET \
'https://api.carrierx.com/core/v2/lookup/dids/15623499000' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Here 15623499000 is the phone number we want to lookup information for.

A successful request will return a 200 response code with the phone number details.

{
    "country_code": "USA",
    "details": {
        "carrier": null,
        "cnam": null,
        "lrn": null
    },
    "e164_format": "+15623499000",
    "in_country_format": "(562) 349-9000",
    "international_format": "+1 562-349-9000",
    "phonenumber": "15623499000",
    "state": "CA"
}
note

The system ignores the additional characters you use besides the digits and the + character. So, you can enter the number as +15623499000, or +1(562) 349-90-00, or +1 562 349 9000, the result will be the same.

Phone Number Lookup Request Arguments​

The phone number lookup request acquires several query arguments which serve various purposes:

  1. The carrier, cnam, and lrn arguments allow the users to get the detailed information about the phone number carrier, its CNAM (if it has any), and location routing number (LRN) associated with it.

    note

    To use these arguments, you need to have some special scopes enabled for your account.

  2. And the country_code and guess query arguments take part in the phone number lookup logic. Refer to this section to find out how these arguments influence the lookup.

tip

Refer to this section of the API reference to learn more about the possible values of the available query arguments and how to use them.

Phone Number Lookup Scopes​

To query the basic information about phone numbers the partner must have the following scope enabled:

  • lookup.dids.read to send requests and lookup general information about phone numbers.
note

This scope is enabled by default for most of the partner accounts, you do not need to do anything to be able to query for basic phone number information.

In case you need the detailed information about the phone numbers, you need the following scopes additionally enabled for your partner account:

  • lookup.dids.allow_carrier to query detailed information about the phone number carrier (using the carrier query argument set to true),
  • lookup.dids.allow_cnam to query detailed information about the phone number CNAM (using the cnam query argument set to true),
  • lookup.dids.allow_lrn to query information about the location routing number associated with the phone number (using the lrn query argument set to true).
tip

By default, the additional phone number lookup scopes are disabled. You cannot query the detailed information about carrier, CNAM, or LRN using CarrierX API. Contact technical support at to enable these options for your account.

As you can see in the example above, the response does not contain the information about the carrier, CNAM, or LRN (all these attributes are returned as null).

To query the detailed information about the phone number, the request should look like this:

curl -X GET \
'https://api.carrierx.com/core/v2/lookup/dids/15623499000?carrier=true&cnam=true&lrn=true' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with the phone number details which will include the available carrier, CNAM, and LRN information (if such details are available for the selected phone number):

{
    "country_code": "USA",
    "details": {
        "carrier": {
            "mcc": null,
            "mnc": null,
            "name": "HD CARRIER",
            "type": "landline"
        },
        "cnam": {
            "name": "LONG BEACH   CA",
            "type": null
        },
        "lrn": "9517999999"
    },
    "e164_format": "+15623499000",
    "in_country_format": "(562) 349-9000",
    "international_format": "+1 562-349-9000",
    "phonenumber": "15623499000",
    "state": "CA"
}

Phone Number Lookup Logic​

CarrierX performs the phone number lookup based on the following logic which goes through two stages:

  1. Check if the number is prefixed with +.
  2. Check if the number is a valid in-country or E.164 number.

Stage #1: Check if the number is prefixed with '+'​

If the queried number is prefixed with + (e.g., +15623499000 or +1 562-349-9000), the system will check for a full E.164 match only.

  • If there is a match, the system will return this match with a 200 success status code.

  • Otherwise, the system will not perform any additional searches and will return the 400 status code.

If the queried phone number does not have the + prefix, the system will go on to stage #2 and check if the number is a valid domestic or E.164 number.

Phone Number Lookup Logic Stage #1

Stage #2: Check if the number is a valid domestic or E.164 number​

At this stage, the system will check if the selected phone number is either a valid domestic (in-country) number or if it is a valid E.164 number (prefix matches a valid country code), or it can be both.

  • If the number is only a valid domestic (in-country) number or only a valid E.164 number, this match is returned.

    If the number is only a domestic (in-country) number, the system also checks the country_code query parameter, to see if the number passed could be valid in the country specified in the request.

    If the country_code query parameter is not set, the system uses country_code = USA by default.

  • If the number can be both, a valid domestic (in-country) number and a valid E.164 number, the system will make a guess. The guess query parameter helps choose between the domestic in_country match and the e164 match. The default guess argument value of e164 will prefer the E.164 number. If you want to explicitly make the system guess a domestic number, you need to set the guess parameter to in_country.

Example​

For example, we send a request querying the information about the 2522037283 phone number. This number can be either

  • a US-based domestic phone number (the international format in this case will be +1 252-203-7283),
  • a Somali-based domestic phone number (the international format in this case will be +252 2 037283),
  • a Germany-based domestic phone number (the international format in this case will be +49 2522 037283).

We want to make sure that the system checks for Somali phone numbers first, that is why we add the country_code=SOM query argument to the request:

curl -X GET \
'https://api.carrierx.com/core/v2/lookup/dids/2522037283?country_code=SOM' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request returns the following response:

{
    "country_code": "SOM",
    "details": {
        "carrier": null,
        "cnam": null,
        "lrn": null
    },
    "e164_format": "+2522037283",
    "in_country_format": "2 037283",
    "international_format": "+252 2 037283",
    "phonenumber": "2522037283",
    "state": null,
}

On the other hand, if we don't add any country code at all, the system we use USA as the country_code and will return a US phome number: +1 252-203-7283.

However, if we clearly add guess=e164, the system will always return the Somali-based phone number independent of what country code we may have added, because the Somali-based phone number is the only number that completely matches the E.164 international numbering plan (all the other numbers match only partially since they have additional country and area code prefixes).

Finally, if the number could not be matched with any available valid phone numbers, the system will return the 400 error status code. If the number format is invalid, the system will return the 404 error status code.

Phone Number Lookup Logic Stage #2

The complete phone number lookup logic looks like this:

Phone Number Lookup Logic

IP Address Lookup​

Besides the phone number lookup, you can query information about IP addresses.

tip

By default, the IP address lookup option is disabled for partner accounts. Contact technical support at support@carrierx.com to enable it for your account.

To query the information about the IP address, you need to send a GET request which contains the selected IP address without the protocol portion:

IP Address Lookup

The request looks like this:

curl -X GET \
'https://api.carrierx.com/core/v2/lookup/ip_addresses/8.8.8.8' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with the IP address details.

For a US-based IP address the region attribute will be equal to null and the state attribute will have a value of one of the states:

{
    "city": "Mountain View",
    "common_name": "United States",
    "iso_3166_alpha_2": "US",
    "iso_3166_alpha_3": "USA",
    "region": null,
    "state": "CA"
}

If you try a Europe-based IP address instead, the state attribute will be null in this case and the region attribute will be filled with the appropriate value:

{
    "city": "Berlin",
    "common_name": "Germany",
    "iso_3166_alpha_2": "DE",
    "iso_3166_alpha_3": "DEU",
    "region": "Berlin",
    "state": null
}

Further Reading​

Phonenumber Lookup and IP2Location Objects API Reference​

Refer to the Phonenumber Lookup and IP2Location objects API reference to get the complete list of their attributes and methods used with them:

Phonenumber Lookup​

IP2Location Object​