GET
/
lookupNumber
curl --location 'https://api.byteflow.app/lookupNumber?phone_number=+11234567890&advanced_mode=false' \
--header 'api_key: <YOUR_API_KEY_HERE>'
{
    "is_voip": false,
    "current_carrier_name": "T-Mobile US-SVR-10X/2",
    "current_carrier_ocn": "152049",
    "original_ocn": "151971",
    "original_carrier_name": "Verizon Wireless:6006 - SVR/2",
    "ported": true,
    "is_landline": false,
    "is_mobile": true,
    "current_imsi": "610140000000000",
    "current_mcc": "310",
    "current_mnc": "260",
    "country": {
        "name": "United States",
        "dial_code": "+1",
        "emoji": "๐Ÿ‡บ๐Ÿ‡ธ",
        "code": "US"
    }
}

This method performs a phone number lookup. We recommend using this for use-cases such as verifying phone numbers to help prevent fraud. Another popular use-case for this is making sure that a phone number can receive SMS messages.

What is advanced mode?

Advanced mode sends a query across the SIGTRAN protocol to perform an HLR lookup on the given phone number. Thus using advanced will give you far more data about the phone number, and it will also be able to identify if the number has been ported to a new carrier; This can lead to more accurate detection among other things.

Advanced mode queries will take slightly longer than basic mode

Query String

phone_number
string

This is the phone number that you want to send the message to

advanced_mode
boolean | undefined

If set to true will perform an advanced lookup.

Headers

api_key
string

This is the API key you created in the dashboard. For more info take a look at Authentication

Basic Response

is_voip
boolean

Wether the phone number is a VOIP phone number.

current_carrier_name
string

The full name of the carrier that the block is registered too.

current_carrier_ocn
string | undefined

The OCN of the carrier the phone number is registered to. Will be undefined in the case of international (non-US&Canada) numbers.

country.name
string

The full name of the country that the number is registered to.

country.dial_code
string

The dial code of the phone number given. e.g: โ€œ+1โ€ for the US

country.emoji
string

The emoji flag representing the country.

country.code
string

The 2 letter abbreviation of the country the number is registered in. e.g: โ€œUSโ€ for the United States

Advanced Response

If you are using advanced_mode you will get the following fields in addition to the basic fields.

original_ocn
string | undefined

If the number was ported to a different phone number this will be the OCN of the original carrier.

original_carrier_name
string | undefined

If the number was ported to a different phone number this will be the full name of the original carrier.

ported
boolean | undefined

A boolean representing if the number has been ported or not. May be undefined for some international (non-US&Canada) numbers.

is_landline
boolean

A boolean representing if the number is a landline

is_mobile
boolean

A boolean representing if the number is mobile

current_imsi
string | undefined

The IMSI of the phone numberโ€™s SIM Card. May be undefined for some international (non-US&Canada) numbers.

current_mcc
string | undefined

The MCC of the current carrier. May be undefined for some international (non-US&Canada) numbers.

current_mnc
string | undefined

The MNC of the current carrier. May be undefined for some international (non-US&Canada) numbers.