API Documentation

Implementation Guide – Find Phone, Email, Name and Address

Introduction

Searchbug Advanced Person Search API allows you to find contact information for people in the US. Results typically include: full name, aka aliases, full current and previous addresses, known phone numbers and their types (wireless or landline), date of birth, date of death if deceased, names of relatives and relatives DOB.

Not all information is available for all records.

Overview

Searchbug has deployed the Advanced Person Search API as an XML/JSON over HTTPS Service. The client’s calling system communicates with Searchbug by sending inquiry data using URL over HTTPS protocol. Searchbug processes the data, and then the Searchbug API service transforms the data into XML or JSON format and returns the data to the client’s calling system.

You can seamlessly integrate Searchbug data with your website, mobile application, intranet, network, customer database (CRM/ERP) or any other system.

Search Fees and Account Setup

Please make sure your account is set up correctly before
you start using the API.

  1. Searchbug account with a prepaid payment plan is required.
  2. To select a prepaid plan, navigate to Your Account page and under the Billing Details section select Switch Plan to determine the amount of funds you would like to add to your account balance.
  3. If you signed up using Google, Facebook, or LinkedIn, please be sure to set a password on your Searchbug account prior to using the API.
  4. Each time you run a query, the search fee is deducted from your prepaid account balance.
  5. Prepaid balance is automatically replenished when your funds run low. During off-peak hours (2AM Pacific Time) our system replenishes prepaid balances below 20% (30% for ACH) of your prepaid threshold (e.g. below $200 for $1000 prepaid plan).

Sending Request

The request should be sent to Searchbug using the following URL format over HTTPS:

Supported search input options

  • First and Last Name (middle name is optional) + DOB
  • First and Last Name (middle name and DOB are optional) + Address, City, State (zip is optional)
  • First and Last Name (middle name and DOB are optional) + City, State (zip is optional)
  • First and Last Name (middle name and DOB are optional) + State (zip is optional)
  • Address, City, State (zip is optional)
  • Phone Number
  • Email Address
<AccountID> Will be provided to you when you create a Searchbug account. If you already have an account, you can find your ID on "Your Account" page after you login to Searchbug.
<Password> Will be selected by you during account registration. You can change your password at any time. It is the same password you use to login to the Searchbug website. Please make sure that your password does not contain @, #, ?, & or = characters that may affect reading the URL. If you have multiple users on your account, you can use the password of any user in your query.
<TYPE> Use api_person2 for Advanced Person Search
  • api_email – to find personal or work email address. This service will also return name and street address, if available. Phone number is not returned.
  • api_phone – to find home, work or mobile phone number. This service will also return name and street address, if available. Email address is not returned.
  • api_na – to find person’s and/or business name and address. This service will also return phone numbers for some personal and most business records. Email address is not returned.
<SRCHD>

Is a search option code. This field is optional. When search option code is specified, we will search based on your instructions, regardless of what’s on the query string. For example, if you are looking for email or phone number and your URL has person’s name and full address:

If you specify &SRCH=ns (stands for name and state), we will search using first name, last name and state. Street address (e.g. ADDRESS=123+Main+St) and city (e.g. CITY=Miami) will be ignored. These two queries will return the same results:

If search option code is missing, we will try to search using all fields on the URL. The only exception is phone and email. If PHONE= or EMAIL= are provided on the URL without search option code, we will search by email address or by phone number only.

These search option codes (SRCH) are supported

  • na – using Person's Name and Address
  • la – using Last Name and Address (only works for finding phone number with api_phone)
  • ncs – using Person's Name, City and State
  • nts – using Person's Name, County and State (only works with api_na)
  • ns – using Person's Name and State
  • n – using Person's Name only
  • ba – using Business Name and Address
  • bcs – using Business Name, City and State
  • bts – using Business Name, County and State (only works with api_na)
  • bs – using Business Name and State
  • bz – using Business Name and ZIP
  • a – using Full Street Address (address, city and state)
  • e – using Email Address only
  • p – using Phone Number only

All search fields below are optional. See Valid Search Combinations below.

<FNAME> First name
<MNAME> Middle initial or name
<LNAME> Last name
<CO_NAME> Company Name (the company you are searching for)
<ADDRESS> Street Address in postal format (e.g. “200 E 69TH ST Apt 27A” or “5 TUDOR CITY PL”). You can include apartment or unit number with the address.
<CITY> City of the residence
<COUNTY> County of the residence (e.g. “San Bernardino”). Only works with api_na. State is required for search by country. Do not include city, when searching by county.
<STATE> State of the residence
<ZIP> Zip Code of the residence
<PHONE> 10-digit phone number in any format (e.g. “212-555-7777” or “222555777” or “(212) 555-7777”
<EMAIL> Email Address (e.g. user@domain.com)
<FORMAT> To get JSON-formatted results, use FORMAT=JSON
Example of the request URL

Checking API Prepaid Balance

To check your current prepaid balance, please use the following URL format over HTTPS

<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>


Receiving Results

Advanced Person Search API results XML example

<result>
<rows>1</rows>
<errors/>
<people>
<person>
<gender/>
<deceased>No</deceased>
<names>
<name>
 <title/>
 <firstName>David</firstName>
 <middleName>P</middleName>
 <lastName>Baker</lastName>
 <nameSuffix/>

Advanced Person Search API results JSON example

"searchTime": "1/26/2024 2:25PM",
"rows": 1,
"errors": "",
"people": {
"person": {
"gender": "",
"deceased": "No",
"names": {
 "#text": "c",
 "name": [
{
"title": "",
"firstName": "David",

Example of No Results

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

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