NAME, ADDRESS, PHONE AND EMAIL API

Implementation Guide

Introduction

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

Searchbug® Name, Address, Phone and Email API allows you to find missing contact information for people and businesses in the US. The API returns person’s first and last name, business name, full address, phone number, and email address.

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 Required. Your account number
PASS 76162c80a0333c91 API Key or account password (not needed if using Bearer Token)
TYPE api_nape Required. Use "api_nape" for this API.
SUBTYPE p Optional. Search option code. Specifies what to search for. If not specified, all available data will be returned (name, address, email, phone)
  • p - Find phone number (records without phone number will not be returned)
  • e - Find email address (records without email will not be returned)
FNAME James First name
LNAME Baker Last name
CO_NAME Bulk Packing Company Name (the company you are searching for)
ADDRESS 200 E 69TH ST Street Address in postal format. Do not include unit number.
CITY MIAMI City of the residence
COUNTY Miami-Dade County of the residence or business (e.g. “San Bernardino”). State is required for search by country. Do not include city, when searching by county.
STATE FL State of the residence
ZIP 33101 Zip Code of the residence
PHONE 2127731234 Phone number. If the phone number is supplied, all other input parameters are ignored, and reverse phone search is performed.

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.
E_MAIL user@domain.com Email Address in a valid format. If the Email is supplied, all other input parameters are ignored, and a reverse email search is performed.

Not all records have email data. Reverse email searches may not always return the results.
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).

Valid Search Combinations:

Valid Email Searches (SUBTYPE=e):

  • search by Person's Name and Address
  • search by Person's Name, City and State
  • search by Person's Name and State
  • search by Person's Name only
  • search by Business Name and Address
  • search by Business Name, City and State
  • search by Business Name and State
  • search by Business Name and ZIP Code
  • search by Phone Number
  • search by Street Address

Valid Phone Searches (SUBTYPE=p):

  • search by Person's Name (First and Last) and Address
  • search by Last Name and Address
  • search by Person's Name, City and State
  • search by Person's Name and State
  • search by Business Name and Address
  • search by Business Name, City and State
  • search by Business Name and State
  • search by Business Name and ZIP Code
  • search by Full Street Address
  • search by Email Address

Valid Name and Address Searches (SUBTYPE is blank):

Phone and email address will also be returned if available

  • search by Person's Name, City and State
  • search by Person's Name, County and State
  • search by Person's Name and State
  • search by Business Name, City and State
  • search by Business Name, County and State
  • search by Business Name and State
  • search by Business Name and ZIP Code
  • search by Phone Number
  • search by Email Address
  • search by Full Street Address

Receiving Results

Below are examples of XML and JSON results. The output structure will be same for all APIs in this category. If data is missing for a particular field, empty tag will be sent (<EMAIL></EMAIL> or EMAIL: "")

  • SRC is SearchBug internal code that is used for troubleshooting
  • PHFND is indicator if the results contain at least one phone number
  • ADFND is indicator if the results contain at least one street address
  • EMFND is indicator if the results contain at least one email address

Example of XML results

                             

<RESULTS>
    <SRC>DBU</SRC>
    <PHFND>X</PHFND>
    <ADFND>X</ADFND>
    </EMFND>
    <RECORD>
        <FNAME>CARLOS</FNAME>        
        <LNAME>TORRES</LNAME>
        <BNAME>GATE SEVEN CREATIVE STUDIOS</BNAME>
        <PHONE>(407) 398-0777</PHONE>
        <ADDRESS>6001 VINELAND RD STE 117</ADDRESS>
        <CITY>ORLANDO</CITY>
        <STATE>FL</STATE>               
        <ZIP>32819</ZIP>
        </EMAIL>        
    </RECORD>       
    <RECORD>
        <FNAME>CARLOS</FNAME>        
        <LNAME>TORRES</LNAME>
        <BNAME>GATE SEVEN CREATIVE STUDIOS</BNAME>
        <PHONE>(407) 730-2780</PHONE>
        <ADDRESS>1325 CHIEF TRL</ADDRESS>
        <CITY>ORLANDO</CITY>
        <STATE>FL</STATE>               
        <ZIP>328825</ZIP>
        </EMAIL>        
    </RECORD>
</RESULTS>

Here is an example of JSON results:

                        
{
    Status: "Success",
    - Data: 	{
        SRC: "DBU",
        PHFND: "X",
        ADFND: "X",
        EMFND: "",
        RECORD: [
        - {
            FNAME: "CARLOS",
            LNAME: "TORRES",            
            BNAME: "",
            PHONE: "(305) 361-9613",                
            ADDRESS: "445 GRAND BAY DR APT 318",                    
            CITY: "KEY BISCAYNE",
            STATE: "FL",
            ZIP: "33149",
            EMAIL: ""
        },
        - {
            FNAME: "CARLOS",
            LNAME: "TORRES",            
            BNAME: "",
            PHONE: "",                
            ADDRESS: "311 JOHNSON RD",                    
            CITY: "SUMMERLAND KEY",
            STATE: "FL",
            ZIP: "331042",
            EMAIL: ""
        }
      ]
    
    },
    Error: ""
  }

Example of No Results

                               
<?xml version="1.0" encoding="ISO-8859-1" standalone="true"?>
<RESULTS>
    <FOUND>NO</FOUND>
</RESULTS>

{
    STATUS: "NORESULTS",
    DATA: "",
    ERROR: ""
}

Error Example - wrong account or password

                                       
<?xml version="1.0" encoding="ISO-8859-1" standalone="true"?>
<RESULTS>
    <ERROR>PASSWORD OR ACCOUNT NUMBER ARE NOT VALID</ERROR>
</RESULTS>

{
    STATUS: "ERROR",
    DATA: "",
    ERROR: "PASSWORD OR ACCOUNT NUMBER ARE NOT VALID"
}

Checking API Prepaid Balance

To check your current prepaid balance, please use the following URL format over HTTPS. Use TYPE_API specific to the API type for which you want to get the stats. This example is for api_loc2.

https://data.searchbug.com/api/search.aspx?CO_CODE=<AccountID>&PASS=<Password>&TYPE=STATUS&TYPE_API=api_loc2 

<RESULTS>
    <API_TYPE>api_loc2</API_TYPE>
    <API_NAME>API - Line Type and Carrier (Standard)</API_NAME>
    <DAILY>1</DAILY>
    <MONTHLY>4</MONTHLY>
    <RATE>0.0100</RATE>
    <BALANCE>47.72</BALANCE>
    <PREPAID>100.00</PREPAID>
    <DATE>01/12/2023</DATE>
</RESULTS>

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.