Get Details for Phone Number

This request returns data for the specified phone number.

get	/lookup/dids/{phonenumber}

Sample

A sample GET request to get the phone number details:

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

Response

200 status code with the phone number details:

{
    "country_code": "USA",
    "details": {
        "carrier": {
            "mcc": "312",
            "mnc": "850",
            "name": "INTELIQUENT",
            "type": "mobile"
        },
        "cnam": null,
        "lrn": null
    },
    "e164_format": "+14353035210",
    "in_country_format": "(435) 303-5210",
    "international_format": "+1 435-303-5210",
    "phonenumber": "14353035210",
    "state": "UT"
}

This request is enabled for Field Filtering.

Required Scopes

To query information for phone numbers the partner must have the following scopes enabled:

• lookup.dids.read to send requests and lookup general information about phone numbers,
• lookup.dids.allow_carrier to query detailed information about the carrier (using the carrier query argument set to true),
• lookup.dids.allow_cnam to query detailed information about the CNAM (using the cnam query argument set to true),
• lookup.dids.allow_lrn to query information about the location routing number (using the lrn query argument set to true).

tip

Contact technical support at support@carrierx.com to enable this option.

Path Arguments

Parameter	Data Type	Description
phonenumber required	string	The phone number to look up.

Query Arguments

Parameter	Data Type	Description
carrier	boolean	Determines if the carrier information should be shown. Values accepted in this field are true and false.
cnam	boolean	Determines if the CNAM information should be shown. Values accepted in this field are true and false.
cnam_ttl	integer	Overrides the default CNAM cache TTL.
country_code	string	The ISO 3166-1 alpha-3 code of the country for this phone number.
guess	string	Optional recommendation whether this number is domestic or not. Values accepted in this field are: e164 for international numbers. in_country for domestic numbers. The default value is e164.
hlr	boolean	Determines if the carrier will be looked up in the Home Location Registry. Values accepted in this field are true and false. The default value is true.
lrn	boolean	Determines if the location routing number should be shown. Values accepted in this field are true and false.

Phone Number Lookup Logic

CarrierX performs the phone number lookup based on the following logic:

• If the queried number is prefixed with +, the system will check for a full E.164 match only.
  • If there is a match, the system will return this match.
  • Otherwise, it will return the 400 status code.
• When the country_code query parameter is passed, the system checks if the number passed could be valid in the country specified in the request (either the 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 no country_code query parameter was passed or if the match did not succeed, the system will check if it is both a valid domestic number or if it is a valid E.164 number (the prefix matches a valid country code).
  • If the number is only a valid domestic 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 domestic (in_country) match and the E.164 match. The default value of e164 will prefer the E.164 number.

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.

info

Refer to our How It Works: Lookup Phone Numbers and IP Addresses section to learn more about the logic of phone numbers lookup.

Using Home Location Registry for Carrier Lookup

The Home Location Registry (HLR) is an external paid database containing data regarding carriers and subscribers. You can set the hlr query argument of your phone number lookup request to true and the system will make an API call to the HLR. The returned results in this case will most likely be more accurate than the results returned without using this flag. Please note that for using this option you will be charged extra.

On the other hand, if the hlr query argument is set to false, the carrier will be determined without the HLR lookup. Only static databases will be used. In this case the mcc and mnc fields can be returned as null in the reply if the phone number is other than a mobile phone number.