Bulk Phone Validation API

Implementation Guide

Introduction

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

This API is suited for Phone ID requests with large number of records (hundreds or even thousands). For individuals requests, you can use our standard APIs.

Searchbug Phone ID Bulk API determines phone line type (landline, cellular, VoIP), current carrier (Phone Company), its OCN number, location, SMS email address for cell phone numbers, porting information (if applicable), and line status (active or disconnected).

The API can also check if phone numbers are on Federal and State Do Not Call (DNC) lists. State DNC list checks are supported for all US States. Both Federal and all State checks are performed at once. The results will indicate if the number is on the Federal list or on a particular state list. We also report if the phone number is listed as a "DNC Complainer". These are people who have complained but have not yet sent demand letters or sued.

In addition to DNC, Searchbug provides the most up-to-date list of phone numbers used in TCPA (Telephone Consumer Protection Act) lawsuits and associated with TCPA litigators. The list also includes TCPA trolls, people who have sent demand letters but have never filed a TCPA lawsuit.

The phone type and carrier are the current (as of today) information on actual carrier and phone type considering number porting.

The API only supports US phone numbers.

4 levels of service (Standard, Advanced, Complete, and DNC & TCPA) are available to meet your needs.

Searchbug® offers four different hybrid API/Bulk phone validation options to meet your specific needs. These APIs are a hybrid design that function as APIs but have the ability to process large-volume lists utilizing our Bulk Upload processing platform.

Are you curious how to easily integrate any of our phone validation APIs into your existing systems? This API Documentation is here to guide you!

This guide includes:

Phone Validation (BULK) API Comparison
Overview
Step 1: Sending Initial Request with Phone Numbers
"Send" API Response
Step 2: Receiving Processed Results
"Receive" API Response
Field Definitions in API Response
Errors

Phone Validation API Comparison

DATA	API FIELD NAME	STANDARD (batch_lnp)	ADVANCED(batch_lnd)	COMPLETE (batch_atn)	DNC & TCPA (batch_dnc)
Record ID	ID	input field	input field	input field	input field
Phone Number	NUMBER	input field	input field	input field	input field
Line Status	STATUS
DNC List	DNC
TCPA Check	TCPA
Line Type	TYPE
Carrier/Provider	CARRIER
SMS Email	SMSEMAIL
Carrier OCN	OCN
Number was Ported	PORTED
Location	LOCATION
State	STATE
Time Zone	TIMEZONE

Overview

The customer's system sends a list of phone numbers with their record ID via POST in JSON format using the Send API.
Searchbug® accepts the data, processes the payment and initiates asynchronous (offline) process to verify phone numbers.
The Send API will return the status of the request (success or failure), number of phone records received, type of service selected, estimated time of completion, cost, payment ID, error details if any, and the most importantly the KEY to retrieve the data with the second Receive API.
Customer schedules the Receive API and passes the KEY to check the processing status and to obtain the results, when ready.

If processing is not finished yet, the Receive API will return status as “Running”, number of records processed so far, percent completion, and estimated time to complete.
If processing is complete, the API will return data in JSON (default) or XML format
If there is an error, the API will show the status as “Stopped” or “Error” with error details.

You can seamlessly integrate Searchbug® data with your CRM platform, web site, internal application or any other system.

Step 1. Sending Request Initial Request with Phone Numbers

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

https://bulk.searchbug.com/c/api/send

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	Required. Your account number
PASS	76162c80a0333c69	API Key or account password (not needed if using Bearer Token)
TYPE	batch_lnp	Required. Use one of these Service Types, based on your needs: batch_lnp - Standard Service (Current Carrier and Line Type) batch_lnd - Advanced Service (Standard + DNC + TCPA) batch_atn - Complete Service (Advanced + Line Status) batch_dnc - DNC + TCPA Only
FORMAT	JSON	Optional. The default is JSON. To get the API response in XML format, pass &FORMAT=XML

Send a list of phone numbers in JSON format in the Body of your POST request. You can include any number of phone records in one request. You can send several requests consecutively and they all will be processed independently.

Use this format for your phone number list:

                    
[
    {
        "id": "<ContactId>",
        "phone": "<Phone>"
    },
    {
        "id" "<ContactId>",
        "phone": "<Phone>"
    }
]

ContactID is a Unique ID associated with phone number. For example, it can be CRM Contact ID or some other identifier. If it does not apply to your case, you can send 1, 2, 3, etc. as ContactID. It's a required field.

Phone is a phone number to verify. It can be in any format. It may contain spaces, dashes, parenthesis, or period. Examples: 212-773-1234, 2127731234, 212.773.1234, (212) 773-1234.

If a phone number contains more than 10 digits, first 10 digits will be used.
Example: you supply 2127731234x567 we use 2127731234.

If a phone number contains 1 as the first digit, it will be considered the US Country Code and will be stripped. Example: you supply 1-212-773-1234 we use 2127731234.

"Send" API Response

If you skip FORMAT or include FORMAT=JSON, the response will be in the JSON format as shown below.

JSON Response:


{
    "SUCCESS": true,
    "KEY": "133712503650672071",
    "TYPE": "batch_atn",
    "RECORDS": "2500",
    "TIME": 14,
    "PRICE": "125.00",
    "PAYMENT_ID": "BTV_ q8acacx8",
    "ERROR": ""
}

If you include FORMAT=XML on the URL, the response will be XML

XML Response:


<RESULTS>
    <SUCCESS>true</SUCCESS>
    <KEY>133710902495274714</KEY>
    <TYPE>batch_lnp</TYPE>
    <RECORDS>800</RECORDS>
    <TIME>4</TIME>
    <PRICE>12.00</PRICE>
    <PAYMENT_ID>BTC_ew1mrkng</PAYMENT_ID>
    <ERROR />    
</RESULTS>

<SUCCESS>	Overall status of the request (true or false)
<KEY>	The ID of the batch request. Send this KEY in the Receive API to get the results (see below)
<TYPE>	Requested service type
<RECORDS>	Total number of phone records received
<TIME>	Expected duration for the phone batch processing in minutes. If value is 0 or null, the results will be ready in less than a minute.
<PRICE>	The cost to process this set of phone numbers
<PAYMENT_ID>	Searchbug Payment ID
<ERROR>	Error details, in case SUCCESS = false

Step 2. Receiving Processed Results

The request should be sent to Searchbug using POST method to this endpoint:

https://bulk.searchbug.com/c/api/receive

You should submit authentication and request parameters via custom POST Headers

Parameter	Value Example	Description
CO_CODE	12345678	Required. Your account number
PASS	76162c80a0333c69	API Key or account password (not needed if using Bearer Token)
KEY	133712503650672071	Required. Batch ID you receive in the response of the Send API
FORMAT	JSON	Optional. The default is JSON. To get the API response in XML format, pass &FORMAT=XML

You can start querying the results immediately or after the time indicated in TIME field of the response of the Send API.

"Receive" API Response - Results are not ready yet

JSON example of the response for the set of phone numbers that is still being processed:

                        
{
    "SUCCESS": true,
    "KEY": "133712503650672071",
    "TYPE": "batch_lnp",
    "STATUS": "Running",
    "START": "Sep 13, 2024 16:42:57",
    "END": "",
    "TIME": "00:00:02",
    "TOFINISH": "8 minutes",
    "MINLEFT": "8",
    "RECORDS": "2000",
    "PROCESSED": "250",
    "PERCENT": "12.50%",
    "PRICE": "$30.00",
    "ERROR": "",
    "DATA": null
}

JSON example of the response with Completed results:

                        
{
    "SUCCESS": true,
    "KEY": "133715978678996543",
    "TYPE": "batch_atn",
    "STATUS": "Complete",
    "START": "Sep 23, 2024 13:45:37",
    "END": "Sep 23, 2024 13:58:23",
    "TIME": "00:12:46",
    "TOFINISH": "",
    "MINLEFT": "0",
    "RECORDS": "100",
    "PROCESSED": "100",
    "PERCENT": "100.00%",
    "PRICE": "$50.00",
    "ERROR": "",
    "DATA": [
        {
            "ID": "164008974_1",
            "NUMBER": "2198083373",
            "STATUS": "ACTIVE",
            "DNC": "FED",
            "TCPA": "YES",
            "TYPE": "CELLULAR",
            "OCN": "6529",
            "PORTED": "NO",
            "CARRIER": "T MOBILE",
            "SMSEMAIL": "2198083373@tmomail.net",
            "LOCATION": "GARY/ELGIN",
            "STATE": "IN",
            "TIMEZONE": "Central Daylight Time (CDT)"
        },
        {
            "ID": "164283583_1",
            "NUMBER": "2036194502",
            "STATUS": "ACTIVE",
            "DNC": "NO",
            "TCPA": "NO",
            "TYPE": "CELLULAR",
            "OCN": "5562",
            "PORTED": "YES",
            "CARRIER": "METRO PCS",
            "SMSEMAIL": "2036194502@mymetropcs.com",
            "LOCATION": "NEW HAVEN/BLOOMFIELD",
            "STATE": "CT",
            "TIMEZONE": "Eastern Daylight Time (EDT)"
        },
        {
            "ID": "164086950_1",
            "NUMBER": "5554590491",
            "STATUS": "INVALID",
            "DNC": "NO",
            "TCPA": "NO",
            "TYPE": "UNKNOWN",
            "OCN": "",
            "PORTED": "",
            "CARRIER": "UNKNOWN",
            "SMSEMAIL": "",
            "LOCATION": "",
            "STATE": "",
            "TIMEZONE": "UNKNOWN"
        },
        {
            "ID": "167570575_1",
            "NUMBER": "8142425707",
            "STATUS": "ACTIVE",
            "DNC": "CPL|PA",
            "TCPA": "NO",
            "TYPE": "CELLULAR",
            "OCN": "4036",
            "PORTED": "YES",
            "CARRIER": "AT&T WIRELESS",
            "SMSEMAIL": "8142425707@txt.att.net",
            "LOCATION": "WSNGTNZN08/BELTSVILLE",
            "STATE": "VA",
            "TIMEZONE": "Eastern Daylight Time (EDT)"
        },
        {
            "ID": "167570787_1",
            "NUMBER": "9897528014",
            "STATUS": "INACTIVE",
            "DNC": "FED",
            "TCPA": "YES",
            "TYPE": "LANDLINE",
            "OCN": "9323",
            "PORTED": "NO",
            "CARRIER": "AT&T INC",
            "SMSEMAIL": "",
            "LOCATION": "SAGINAW",
            "STATE": "MI",
            "TIMEZONE": "Eastern Daylight Time (EDT)"
        }
    ]
}

Field Definitions for the Receive API response

Header - Processing Status

<SUCCESS>	Overall Success Status (true/false)
<KEY>	Batch ID of the request
<STATUS>	Batch processing status (Running, Completed, Stopped, Failed)
<START>	Date and time when batch was started
<END>	Date and time when batch finished. Blank for batches not yet completed.
<TIME>	Time the batch was running
<TOFINISH>	Estimated time to finish in words (1 to 5 min, 1 hr 13 min, etc)
<MINLEFT>	Estimated numeric value of minutes left to finish the batch
<RECORDS>	Number of records received and being processed
<PROCESSED>	Number of records processed so far
<PERCENT>	Percent complete
<PRICE>	Cost of the processing of the current batch
<ERROR>	Error details

DATA - Phone Verification Results

<ID>	Record ID associated with the phone number supplied in the Send API
<NUMBER>	Phone number
<STATUS>	This is an indicator if a line is active or disconnected. Values for batch_atn: ACTIVE, INACTIVE, INVALID for batch_atn or NOT_VERIFIED for batch_lpn and batch_lnp.
<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 Blank - for batch_lnp (not searched)
<TCPA>	YES/NO. Indicates if phone number was used in the Telephone Consumer Protection ACT (TCPA) litigation from 2000 to present day. The service batch_lnp will return blank value.
<TYPE>	Current phone line type. Will contain LANDLINE, CELLULAR or UNKNOWN (invalid phone number)
<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.
<CARRIER>	Current phone company (local exchange carrier) name. For VoIP phone numbers the name of the VoIP reseller is shown e.g. BANDWIDTH.COM, not an actual service provider, which could be Vonage, Magic Jack, RingCentral, VoIP.com, Google Voice or others.
<SMSEMAIL>	Email address for sending a text message to the cell phone number customer.
<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)
<TIMEZONE>	Time Zone of the phone number

Errors

Send API error example:

                        
{
    "SUCCESS": false,
    "KEY": "131600931558027403",
    "TYPE": "batch_atn",
    "RECORDS": "2500",
    "TIME": 14,
    "PRICE": "125.00",
    "PAYMENT_ID": "BTV_ q8acacx8",
    "ERROR": "The payment failed. Please update your credit card and start over."
}

Receive API error example:

                        
{
    "SUCCESS": false,
    "KEY": "133712503650672071",
    "TYPE": "batch_lnp",
    "STATUS": "Failed",
    "START": "Sep 13, 2024 16:42:57",
    "END": "",
    "TIME": "",
    "TOFINISH": "12 minutes",
    "MINLEFT": "12",
    "RECORDS": "1000",
    "PROCESSED": "0",
    "PERCENT": "0.0%",
    "PRICE": "$5.00",
    "ERROR": "Unable to connect to any of the specified MySQL hosts”,
    "DATA": null
}

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.

Bulk Phone Validation API

Introduction

Phone Validation API Comparison

Overview

Step 1. Sending Request Initial Request with Phone Numbers

"Send" API Response

Step 2. Receiving Processed Results

"Receive" API Response - Results are not ready yet

Field Definitions for the Receive API response

Errors

Account

How It Works

Batch Processing

Developer APIs

Resources and Tools

Assisted Searches

Why Searchbug

Company