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:
-
The
carrier
,cnam
, andlrn
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. -
And the
country_code
andguess
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 thecarrier
query argument set totrue
),lookup.dids.allow_cnam
to query detailed information about the phone number CNAM (using thecnam
query argument set totrue
),lookup.dids.allow_lrn
to query information about the location routing number associated with the phone number (using thelrn
query argument set totrue
).
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:
- Check if the number is prefixed with
+
. - Check if the
country_code
parameter is passed. - 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.
We want to make sure that the system checks for German phone numbers first, that is why we add the country_code=DEU
query argument to the request:
curl -X GET \
'https://api.carrierx.com/core/v2/lookup/dids/447719262246?country_code=DEU' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
A successful request returns the following response:
{
"country_code": "DEU",
"details": {
"carrier": null,
"cnam": null,
"lrn": null
},
"e164_format": "+49447719262246",
"in_country_format": "04477 19262246",
"international_format": "+49 4477 19262246",
"phonenumber": "447719262246",
"state": null
}
-
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 defaultguess
argument value ofnorth_america
will prefer the NANP number. If you want to explicitly make the system guess an E.164 number, you need to set theguess
parameter toe164
.
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:
Phonenumber Lookup
IP2Location Object
How It Works
Read the following articles to get a better understanding of how things work in CarrierX: