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:

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

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).

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 three stages:

1. Check if the number is prefixed with +.
2. Check if the country_code parameter is passed.
3. Check if the number is a valid NANP 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 request contains the country_code query argument.

Stage #2: Check if the ‘country_code’ parameter is passed

When the request contains the country_code query parameter, the system checks if the number passed could be valid in the country specified in the request (either in-country format or by international prefix).

• If the number is valid against the specified country, the system returns this value immediately, no further checks are made.

• If the country_code argument is missing, the system goes on to stage #3.

• If the country_code argument is present, but the selected phone number is not valid for the country specified in the request, the system will also go on to stage #3.

Stage #3: Check if the number is a valid NANP or E.164 number

If no country_code query parameter was passed or if the match did not succeed, the system will check if the selected phone number is both a valid North American Numbering Plan (NANP) number (a 10-digit number + a valid numbering plan area) and if it is a valid E.164 number (prefix matches a valid country code).

• If the number is only a valid NANP number or only a valid E.164 number, this match is returned.

• Otherwise, the system will make a guess. The guess query parameter parameter helps choose between the NANP match and the E.164 match. The default guess argument value of north_america will prefer the NANP number. If you want to explicitly make the system guess an E.164 number, you need to set the guess parameter to e164.

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.

The complete phone number lookup logic looks like this:

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:

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:

How It Works

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

• Getting Started
• How It Works
• CarrierX Endpoints
• Trunk Groups and Trunks
• Prefix Routing
• Access Control
• Transformations
• STIR/SHAKEN
• Storing Files with CarrierX
• Send Push Notifications to Devices
• Using OAuth Tokens