Phone Validation APIs

Implementation Guide

Introduction

Please see the Overview Page to review account setup, authentication instructions, and other common API features.

Searchbug® Phone Validation APIs provide real-time validation of phone numbers. They allow you to:

Identify the line type: landline (fixed), mobile (wireless), or VoIP (Voice over IP)
Retrieve the current or original carrier, including the carrier's name, OCN (Operating Company Number), location, local calling area, and time zone
Detect if a number has been ported to a different carrier
Obtain SMS gateway email addresses for mobile numbers (when available)
Check if a number is reachable (active) or disconnected
Verify inclusion on Federal and State Do Not Call (DNC) lists
Flag numbers associated with TCPA litigation, known litigators, and high-risk contacts (including “TCPA trolls”)
Return Caller ID (CNAM) information, including the 15-character name associated with a phone number

DNC and TCPA Compliance

State DNC list checks are supported for all US States. Both Federal and State checks are performed in a single request, with results showing which lists (if any) a number appears on. Additionally, the “DNC Complainer” flag identifies individuals who have submitted complaints but not yet pursued legal action.

Geographic Coverage

Standard Phone ID API supports both US and Canadian phone numbers
The rest of the APIs are for US numbers only

Data is sourced from authoritative telecommunications databases, including the North American Numbering Plan Administration (NANPA), Canadian Numbering Administrator, live telecom data, and proprietary Searchbug sources.

Accuracy Levels for Line Type

Standard Phone ID API: about 70% accuracy (original carrier only, no porting check; monthly updates)
The rest of the APIs: Up to 99% accuracy, with real-time carrier data and full portability checks

Phone Validation API Comparison

	Standard	Advanced	Adv + DNC	Adv + Caller ID	Reachable Number	Reachable + Caller ID	Complete	Active	DNC List	Re- assigned	Caller ID
	api_loc3	api_lnp3	api_lnd2	api_lnc2	api_atn3	api_atc	api_atx2	api_atn	api_dnc2	api_rnd	api_cnam
Orig. Line Type
Orig. Carrier
Curr. Line Type
Curr. Carrier
LNP Port check
SMS email
OCN
Location
State
Time zone
DNC Check*
TCPA Check
Line Status
Caller ID
Reassigned Number
Price Factor	1	x 1.5	x 3	x 7	x 5	x 9	x 10	x 4	x 2	x 4	x 6

* In addition to Federal DNC List check, State DNC List verification is available for ALL states. We also report if the phone number listed as "DNC Complainer". These are the people who have complained but have not yet sent demand letters or sued.

Need to verify large volumes of phone numbers? Check out our Bulk API.

Sending Request

The request should be sent to Searchbug using the following URL using the POST method:

https://data.searchbug.com/api/search.aspx

Search Parameters

You can submit your request via:

POST Header: Parameters sent as custom headers
POST Body: Parameters sent as form-data

Parameter	Value Example	Description
CO_CODE	12345678	API Key or account password (not needed if using Bearer Token)
PASS	76162c80a0333c91	API Key or account password (not needed if using Bearer Token)
TYPE	api_lnp3	Required. Use one of these API Types, based on your needs: api_loc3 - Standard Phone ID api_lnp3 - Advanced Phone ID api_lnd2 - Advanced Phone ID + DNC/TCPA api_lnc2 - Advanced Phone ID + Caller ID api_atn3 - Advanced + Reachable + DNC/TCPA api_atc - Advanced + Reachable + Caller ID api_atx2 - Advanced + Reachable + DNC/TCPA + Caller ID api_atn - Active/Reachable Phone Number (only) api_dnc2 - Do Not Call List and TCPA (only) api_cnam - Caller ID / CNAM (only)
F	2127731234	Required. Phone number(s) to verify. Accepts one (F=2127731234) or more numbers as a comma-separated list (e.g., F=2127731234, 2127731235). The phone numbers can be in any format. They can contain spaces, dashes, parentheses, or periods. Examples: 212-773-1234, 2127731234, 212.773.1234, (212) 773-1234. If a phone number contains more than 10 digits, the first 10 digits will be used. Example: you supply 2127731234x567 we use 2127731234. If phone number contains 1 as the first digit, it will be considered the US Country Code and stripped. Example: if you supply 1-212-773-1234 or +12127731234, we will use 2127731234 to verify.
FORMAT	JSON	Optional. The default is XML. To get results in JSON format, pass FORMAT=JSON
REF	Client1	Optional. Used for API usage tracking per application or customer (100 char max).

Example of the request:

"CO_CODE=12345678"
"TYPE=api_lnp3"
"F=5551234567,5559876543"
"FORMAT=JSON"

Example of the Postman test:

For queries involving active/disconnected line status (api_atn3, api_atc, api_atx2, api_atn), it is not recommended to send more than 10 numbers per query. Since line status is not a simple database query, the time required to conduct a real-time verification takes a little longer. APIs that do not include line status do not have this limitation.

A separate Phone Validation Bulk API is available for phone verification requests with hundreds or even thousands of records with one request. Click here.

Receiving Results

APIs With Unique Results Format. These APIs api_dnc2, api_cnam, and api_atn, return results in their own simplified format. The rest of the APIs have a common shared format.

DNC API (api_dnc2) - XML


<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<RESULTS>
    <PHONE>
        <NUMBER>3077721924</NUMBER>
        <NUMBER2>(307) 772-1924</NUMBER2>
        <DNC>FED,WY</DNC>
        <TCPA>NO</TCPA>
        <CODE>TLX</CODE>
    </PHONE>
    <STATS>
        <DATE>05/22/2023</DATE>
        <DAILY>3</DAILY>
        <MONTHLY>7</MONTHLY>
        <RATE>0.02</RATE>
        <BALANCE>554</BALANCE>        
    </STATS>    
</RESULTS>

DNC API (api_dnc2) - JSON

                        
{
    "Status": "Success",
    "Data": {
        "PHONE": {
            "NUMBER": "3077721924",
            "NUMBER2": "(307) 772-1924",
            "DNC": "YES",
            "TCPA": "NO",
            "CODE": "TLX"
        },
        "STATS": {
            "DATE": "05/22/2023",
            "DAILY": "1",
            "MONTHLY": "2",
            "RATE": "0.02",
            "BALANCE": "47.71973"
        }
    },
    "Error": null
}

Caller ID API (api_cnam) - XML


<RESULTS>
    <PHONE>
        <NUMBER>9283997589</NUMBER>
        <NUMBER2>(928) 399-7589</NUMBER2>
        <CNAM>STEWART TITLE</CNAM>
        <CODE>OPN</CODE>
    </PHONE>
    <STATS>
        <DATE>03/25/2021</DATE>
        <DAILY>2</DAILY>
        <MONTHLY>2</MONTHLY>
        <RATE>0.06</RATE>
        <BALANCE>598.9648</BALANCE>        
    </STATS>    
</RESULTS>

Caller ID API (api_cnam) - JSON

                        
{
    "RESULTS": { 
        "PHONE": {
            "NUMBER": 9283997589,
            "NUMBER2": "(928) 399-7589", 
            "CNAM": "STEWART TITLE", 
            "CODE": "OPN"
        },
        "STATS": {
            "DATE": "03/25/2021",
            "DAILY": 2,
            "MONTHLY": 2,
            "RATE": 0.06,
            "BALANCE": 598.9648
        }
    }
}

Active Phone Number API (api_atn) - XML

                        

    <PHONE>
        <NUMBER>9496392730</NUMBER>
        <NUMBER2>(949) 639-2730</NUMBER2>
        <STATUS>ACTIVE</STATUS>
        <CODE>RVS</CODE>
    </PHONE>
    <STATS>
        <DATE>03/27/2021</DATE>
        <DAILY>7</DAILY>
        <MONTHLY>8</MONTHLY>
        <RATE>0.04</RATE>
        <BALANCE>554</BALANCE>
    </STATS>
</RESULTS>

Active Phone Number API (api_atn) - JSON

                        
{
    "RESULTS": { 
        "PHONE": {
            "NUMBER": 9496392730,
            "NUMBER2": "(949) 639-2730", 
            "STATUS": "ACTIVE", 
            "CODE": "RVS"
        },
        "STATS": {
            "DATE": "03/27/2021",
            "DAILY": 7,
            "MONTHLY": 8,
            "RATE": 0.04,
            "BALANCE": 554
        }
    }
}

APIs With Common Format

Advanced Phone ID + DNC + TCPA (api_lnd2) - XML

                    
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?> 
<RESULTS>
    <PHONE>
        <NUMBER>7192500060</NUMBER>
        <NUMBER2>(719) 250-0060</NUMBER2>
        <CNAM></CNAM>
        <STATUS></STATUS>
        <DNC>CPL, CO</DNC>
        <TCPA>NO</TCPA>
        <TYPE>CELLULAR</TYPE>
        <VOIP>NO</VOIP>
        <CARRIER>VERIZON WIRELESS</CARRIER>
        <0CN>6567</0CN>
        <PORTED>NO</PORTED>
        <SMSEMAIL>7192500060@vtext.com</SMSEMAIL>
        <STATE></STATE>
        <LOCATION>PUEBLO/COLORADO SPRINGS</LOCATION>
        <LATA>Colorado Springs CO</LATA>
        <TIMEZONE>MOUNTAIN DAYLIGHT TIME (MDT)</TIMEZONE> 
        <TIMENOW>5/22/2023 5:59:47 PM</TIMENOW>
        <CODE>LOC</CODE>
    </PHONE>
    <STATS>
        <DATE>05/22/2023</DATE>
        <DAILY>23</DAILY>
        <MONTHLY>29</MONTHLY>
        <RATE>0.03</RATE>
        <BALANCE>554</BALANCE>
    </STATS>
</RESULTS>

Advanced Phone ID + DNC + TCPA (api_lnd2) - JSON

                    
{
    "Status": "Success",
    "Data": {
        "PHONE": {
            "NUMBER": "7192500060",
            "NUMBER2": "(719) 250-0060",
            "CNAM": null,
            "STATUS": null,
            "DNC": "YES",
            "TCPA": "NO",
            "TYPE": "CELLULAR",
            "VOIP": "NO",
            "CARRIER": "VERIZON WIRELESS",
            "OCN": "6567",
            "PORTED": "NO",
            "SMSEMAIL": "7192500060@vtext.com",
            "STATE": null,
            "LOCATION": "PUEBLO/COLORADO SPRINGS",
            "LATA": "Colorado Springs CO",
            "TIMEZONE": "MOUNTAIN DAYLIGHT TIME (MDT)",
            "TIMENOW": "5/22/2023 4:32:33 PM",
            "CODE": "LOC"
        },
        "STATS": {
            "DATE": "05/22/2023",
            "DAILY": "2",
            "MONTHLY": "3",
            "RATE": "0.03",
            "BALANCE": "47.71973"
        }
    },
    "Error": null
}

Reachable + Caller API (api_lnc2) - XML

                    
<RESULTS>
    <PHONE>
        <NUMBER>9283997589</NUMBER>
        <NUMBER2>(928) 399-7589</NUMBER2>
        <CNAM>STEWARD TITLE</CNAM>
        <STATUS/>
        <DNC/>
        <TCPA>NO</TCPA>
        <TYPE>LANDLINE</TYPE>
        <VOIP>NO</VOIP>
        <CARRIER>NEUTRAL TANDEM-ILLINOIS - IL</CARRIER>
        <0CN>505B</OCN>
        <PORTED>YES</PORTED>
        <SMSEMAIL/>
        <STATE>AZ</STATE>
        <LOCATION>SEDONA</LOCATION>
        <LATA>Phoenix AZ (plus Winterhvn CA, Spirit Mnt NV, Glen Cyn, UT)</LATA>
        <TIMEZONE>MOUNTAIN STANDARD TIME (MST)</TIMEZONE>
        <TIMENOW>3/25/2021 10:43:41 PM</TIMENOW>
        <CODE>LRN</CODE>
    </PHONE>
    <STATS>
        <DATE>03/25/2021</DATE>
        <DAILY>7</DAILY>
        <MONTHLY>7</MONTHLY>
        <RATE>0.07</RATE>
        <BALANCE>599.2948</BALANCE>
    </STATS>
</RESULTS>

Reachable + Caller API (api_lnc2) - JSON

                    

{
    "RESULTS": {
        "PHONE": {
            "NUMBER": 9283997589,
            "NUMBER2": "(928) 399-7589",
            "CNAM": "STEWARD TITLE",
            "STATUS": "",
            "DNC": "",
            EWARD: "",
            "TCPA": "NO",
            "TYPE": "LANDLINE",
            "VOIP": "NO",
            "CARRIER": "NEUTRAL TANDEM-ILLINOIS - IL",
            "OCN": "505B",
            "PORTED": "YES",
            "SMSEMAIL": "",
            "STATE": "AZ",
            "LOCATION": "SEDONA",
            "LATA": "Phoenix AZ (plus Winterhvn CA, Spirit Mnt NV, Glen Cyn, UT)", 
            "TIMEZONE": "MOUNTAIN STANDARD TIME (MST)",
            "TIMENOW": "3/25/2021 10:43:41 PM",
            "CODE": "LRN"
        },
            "STATS": {
            "DATE": "03/25/2021",
            "DAILY": 7,
            "MONTHLY": 7,
            "RATE": 0.07,        
            "BALANCE": 599.2948
        }
    }
}

Multiple Results

If more than one phone number is sent, <PHONE>... </PHONE> node will be repeated in the results

                    
<PHONE>
    <NUMBER>9493000641</NUMBER>
    <NUMBER2>(949) 300-0641</NUMBER2>
    <CNAM>BREDENSTEINER R</CNAM>
    <STATUS/>
    <DNC/>
    <TCPA/>
    <TYPE>CELLULAR</TYPE>
    <VOIP>NO</VOIP>
    <CARRIER>AT&amp;amp;T WIRELESS</CARRIER>
    <OCN>6010</OCN>
    <PORTED>NO</PORTED>
    <SMSEMAIL>9493000641@txt.att.net</SMSEMAIL>
    <STATE/>
    <LOCATION>IRVINE/ANAHEIM</LOCATION>
    <LATA>Los Angeles CA (includes La Paz County, AZ)</LATA>
    <TIMEZONE>PACIFIC STANDARD TIME (PST)</TIMEZONE>
    <TIMENOW>2/10/2024 10:41:20 AM</TIMENOW>
    <CODE>LOC</CODE>    
</PHONE>
<PHONE>
    <NUMBER>8156853109</NUMBER>
    <NUMBER2>(815) 685-3109</NUMBER2>
    <CNAM>JOLIET IL</CNAM>
    <STATUS/>    
    <DNC/>
    <TCPA/>
    <TYPE>CELLULAR</TYPE>
    <VOIP>NO</VOIP>
    <CARRIER>T MOBILE</CARRIER>
    <OCN>6529</OCN>
    <PORTED>YES</PORTED>
    <SMSEMAIL>8156853109@tmomail.net</SMSEMAIL>
    <STATE/>
    <LOCATION>JOLIET/BURR RIDGE</LOCATION>
    <LATA>Chicago IL METRO (includes close parts of IN and WI)</LATA>
    <TIMEZONE>CENTRAL STANDARD TIME (CST)</TIMEZONE>
    <TIMENOW>2/10/2024 12:41:21 PM</TIMENOW>
    <CODE>LRN</CODE>
</PHONE>

No Results

If no results are found for a given phone number. The API will return this response. For example, this scenario may occur if the area code is invalid, the phone number has not yet been issued, or you supplied invalid number (less than 10 digits)

                    
<RESULTS>
    <PHONE>
        <NUMBER>9283997589</NUMBER>
        <NUMBER2>(928) 399-7589</NUMBER2>
        </CNAM>
        <STATUS/>
        <DNC/>
        <TCPA/>
        <TYPE>UNKNOWN</TYPE>
        <VOIP/>
        <CARRIER>UNKNOWN</CARRIER>
        <0CN/>
        <PORTED/>
        <SMSEMAIL/>
        <STATE/>
        <LOCATION/>
        <LATA/>
        <TIMEZONE>UNKNOWN</TIMEZONE>
        <TIMENOW>3/25/2021 10:59:43 PM</TIMENOW>
        <CODE>LOC</CODE>
    </PHONE>
    <STATS>
        <DATE>03/25/2021</DATE>
        <DAILY>4</DAILY>
        <MONTHLY>4</MONTHLY>
        <RATE>0.01</RATE>
        <BALANCE>599.8348</BALANCE>
    </STATS>
</RESULTS>

Field Definitions in API Response

<PHONE NUMBER>	10-digit phone number used for processing (e.g. 9495001234)
<NUMBER2>	Formatted number (e.g. (949) 500-1234)
<CNAM>	Caller ID, 15-character name associated with the phone number
<STATUS>	This is an indicator if a line is active or disconnected. Reported only by APIs containing Reachable Phone Number service
<DNC>	DNC field will return NO if number is "clean", meaning it's not on any state or federal DNC list and it's not a DNC Complainer. Otherwise, the results will include one or more codes separated by comma. The presence on a state DNC list will be marked with a two-letter state code, Federal - FED, DNC Complainer - CPL. Examples: Federal DNC only: FED Texas DNC only: TX Federal and Texas DNC: FED,TX Colorado and Texas DNC: CO,TX Federal, Colorado and Texas DNC: FED,CO,TX Federal DNC, DNC Complainer and Texas DNC: FED,CPL,TX Not on DNC list: NO
<TCPA>	Yes/No. Indicates if phone number was used in the Telephone Consumer Protection ACT (TCPA) litigation from 2000 to present day.
<TYPE>	Phone line type. Will contain LANDLINE, CELLULAR or UNKNOWN
<VOIP>	Will contain YES if number is VoIP number, otherwise will say NO
<CARRIER>	Phone company (local exchange carrier) name. For Standard Phone ID API the original carrier is shown. For VoIP phone numbers the name of the VoIP reseller is shown e.g. BANDWIDTH.COM, not an actual service provider, which could be any number of providers such as Vonage, Magic Jack, RingCentral, VoIP.com, Google Voice or others.
<OCN>	Operating Company Number, a unique carrier ID. For Standard Phone ID API OCN of the original carrier is shown.
<PORTED>	Will show YES for ported numbers, NO for numbers never ported. Will be blank for Standard API (api_loc3)
<SMSEMAIL>	Email address for sending a text message to the cell phone number.
<STATE>	US State or Canadian Province for the phone number
<LOCATION>	Will show Rate Center and/or Central Office location. Can be city name (SEATTLE), city abbreviation (NEWPORTBCH) or code (NWYRCYZN01)
<LATA>	Local Access and Transport Area, description of a local calling area
<TIME ZONE>	Time Zone of the phone number
<TIME NOW>	Time in the phone number's time zone at the time of the API request
<CODE>	Searchbug internal code used for troubleshooting. May change over time
<STATS>	Daily and monthly usage starts, search cost, and account balance DATE - Date of current request DAILY - Daily usage. Number of today's requests MONTHLY - Monthly usage. Number of requests in the current month RATE - Current price for the API. Rate resets every month and goes down with usage. BALANCE - Current account balance. Automatically recharged when balance runs out.

For further technical details and customer support, please chat with us, email us, or call us (800) 990-2939.

For sales and pricing information please contact sales@searchbug.com.

Phone Validation APIs

Introduction

Phone Validation API Comparison

Sending Request

Receiving Results

APIs With Common Format

Multiple Results

No Results

Field Definitions in API Response

Account

How It Works

Batch Processing

Developer APIs

Resources and Tools

Assisted Searches

Why Searchbug

Company