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