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 |
| Standard | Advanced | |
|---|---|---|
| api_loc3 | api_lnp3 | |
| 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 |
| Adv + DNC |
Adv + Caller ID |
|
|---|---|---|
| api_lnd2 | api_lnc2 | |
| 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 |
x 3 | x 7 |
| Reachable Number |
Reachable + Caller ID |
|
|---|---|---|
| api_atn3 | api_atc | |
| 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 |
x 5 | x 9 |
| Complete | Active | |
|---|---|---|
| api_atx2 | api_atn | |
| 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 |
x 10 | x 4 |
| DNC List | Re- assigned |
|
|---|---|---|
| api_dnc2 | api_rnd | |
| 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 |
x 2 | x 4 |
| Caller ID | |
|---|---|
| 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 |
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
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:
"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.
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.
