How It Works

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"
}

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.

  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.

Phone Number Lookup Scopes

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

In case you need the detailed information about the phone numbers, you need the following scopes additionally enabled for your partner 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 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.

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.

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

How It Works

Read the following articles to get a better understanding of how things work in CarrierX: