# USPhoneBook Scraper - Phones, Emails, Addresses & Relatives (`memo23/usphonebook-scraper`) Actor

Search USPhoneBook by name, state and city, or by phone number, and get one row per person: every phone with line type and carrier, emails, current and past addresses with dates, age and birth month, aliases, relatives and associates. Batch hundreds of lookups in one run. CSV-ready.

- **URL**: https://apify.com/memo23/usphonebook-scraper.md
- **Developed by:** [Muhamed Didovic](https://apify.com/memo23) (community)
- **Categories:** Lead generation
- **Features:** Limited permissions
- **Stats:** 4 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 person founds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## USPhoneBook Scraper - People Search: Phones, Addresses & Relatives

Turn a list of names or phone numbers into full US person records in one run. Search USPhoneBook.com by name (narrowed by state and city), look up who owns a phone number, or paste USPhoneBook links, and get one clean row per person: every phone number with line type and carrier, email addresses, current and past street addresses with dates, age and birth month, aliases, relatives and associates.

![How USPhoneBook Scraper works](https://raw.githubusercontent.com/muhamed-didovic/muhamed-didovic.github.io/main/assets/how-it-works-usphonebook.png)

### Why Use This Scraper?

- ✅ **Full profiles, not just search snippets**: each person's complete record with all listed phones, emails and street addresses
- ✅ **Phones with context**: line type (Wireless, Landline, Voip), carrier, last report date and which number is current
- ✅ **Address history with dates**: every past address with the months the person lived there
- ✅ **Reverse phone lookup**: the current owner of a number plus earlier owners, each as a full person row
- ✅ **Batches**: hundreds of names and phone numbers in one run, with a per-search cap so one common name cannot eat the run
- ✅ **Clean name and location matching**: lookalike names and people from other states that the site mixes into results are left out, and never charged
- ✅ **Spreadsheet-ready**: optional Phone-1 / Email-1 columns for CRMs and skip-trace sheets
- ✅ **Nothing to set up**: no login, no account, no proxy settings

### Overview

USPhoneBook Scraper is built for skip tracers, real estate investors, collections and lead-generation teams, and researchers who need structured US people data without copying it off the site by hand.

Whatever you start from (a name, a phone number or a pasted link), the dataset is a stream of person records, one row per person. A name search for "John Smith" in Austin, TX returns the matching John Smiths; a phone lookup returns the number's current owner and its earlier owners. A person found by two of your searches is saved once.

### Supported Inputs

| Input | Example | What you get |
|---|---|---|
| Name + state + city | John Smith, TX, Austin | The people with that name and an address in that state, most relevant to the city first |
| Name + state | Robert Johnson, NY | The people with that name and an address in that state |
| Name only | Maria Garcia | The same, nationwide |
| Phone number | (803) 555-0199 | The number's current owner, then earlier owners |
| Name search link | `https://www.usphonebook.com/john-smith/tx/austin` | Every person on that page and the following pages |
| Phone lookup link | `https://www.usphonebook.com/803-555-0199` | As a phone number |
| Profile link | `https://www.usphonebook.com/john-smith/UxExampleIdForJohnSmith0000aB` | That one person |

Address pages on USPhoneBook no longer list residents, so address links are skipped with a note in the log.

### Use Cases

- **Skip tracing**: find current phones and addresses for a list of owners, debtors or heirs
- **Real estate investing**: reach property owners and their relatives from a name list
- **Caller identification**: find out who owns a list of phone numbers and how to reach them otherwise
- **Lead enrichment**: add phones, emails and addresses to names in your CRM
- **Research and due diligence**: address history, aliases and family connections for a person
- **Data checks**: confirm that a phone number or address still belongs to the person on file

### How It Works

1. **You enter** names (with state and city if you know them), phone numbers, or USPhoneBook links.
2. **The actor reads the search results**, page after page, until it has as many people as you asked for, and leaves out lookalike names.
3. **It opens each person's full profile** and collects every phone, email, address, relative, associate, alias and workplace.
4. **You get one row per person** in the dataset, ready to download as JSON, CSV or Excel or to read through the Apify API.

### Input Configuration

#### Input fields

| Field | Type | Description |
|---|---|---|
| `firstName`, `lastName` | string | The name to search for |
| `state` | string | Two-letter US state code that narrows the search (optional) |
| `city` | string | City that narrows it further; needs a state (optional) |
| `matchLocation` | boolean | Leave out people with no current or past address in the chosen state (default on); off returns everyone the site lists |
| `phoneNumbers` | array | US phone numbers to look up, any format |
| `searches` | array | Many name searches in one run: `[{"firstName":"Jane","lastName":"Doe","state":"FL","city":"Miami"}]`; an entry with only `phone` is a phone lookup |
| `maxItemsPerSearch` | integer | People kept per search; defaults to 3 when you run more than one search |
| `startUrls` | array | USPhoneBook name search, phone lookup or profile links; they replace every search |
| `maxItems` | integer | The most people this run returns (default 10, up to 5,000) |
| `openProfiles` | boolean | Open each full profile (default on). Off returns the search-results summary only |
| `flattenedOutput` | boolean | Adds Phone-1...Phone-5, Email-1...Email-5 and address columns |
| `maxConcurrency` | integer | Pages loaded at the same time (default 5) |

Phone numbers and `searches` replace the single name search at the top of the form, so a batch never also runs the prefilled name.

#### Common scenarios

**One person in one city**

```json
{ "firstName": "John", "lastName": "Smith", "state": "TX", "city": "Austin", "maxItems": 10 }
```

**Who owns these numbers?**

```json
{ "phoneNumbers": ["(803) 555-0199", "512-555-0143"], "maxItems": 20 }
```

**A list of owners, three candidates each, spreadsheet columns**

```json
{
  "searches": [
    { "firstName": "Maria", "lastName": "Garcia", "state": "CA", "city": "Los Angeles" },
    { "firstName": "Robert", "lastName": "Johnson", "state": "NY", "city": "New York" }
  ],
  "maxItemsPerSearch": 3,
  "maxItems": 100,
  "flattenedOutput": true
}
```

**Pasted links**

```json
{ "startUrls": ["https://www.usphonebook.com/john-smith/tx/austin"], "maxItems": 50 }
```

### Output Overview

Every row is one person. With full details on (the default) a row carries:

- **Identity**: `fullName`, `firstName`, `middleName`, `lastName`, `age`, `bornMonthYear`, `birthYear`, `aliases`, `deceased`
- **Phones**: `phones[]` with `number`, `type`, `carrier`, `lastReported`, `isPrimary`, and `primaryPhone`
- **Emails**: `emails[]`
- **Addresses**: `currentAddress` and `pastAddresses[]` with street, city, state, ZIP and the dates lived there
- **People**: `relatives[]` and `associates[]` with names and profile links
- **Work**: `workplaces[]` with job title, location and industry (employer when the site shows it)
- **Search echo**: `query`, `Search Option`, `Input Given`, `searchUrl`, `matchType` (for phone lookups), `searchedAt`, `scrapedAt`

With full details off, a row has the name, age, city and state, past cities and relatives, and `detailsFetched` is `false`.

### Output Samples

A trimmed row from a name search:

```json
{
  "type": "person",
  "personId": "UxExampleIdForJohnSmith0000aB",
  "profileUrl": "https://www.usphonebook.com/john-smith/UxExampleIdForJohnSmith0000aB",
  "fullName": "John Lee Smith",
  "firstName": "John",
  "middleName": "Lee",
  "lastName": "Smith",
  "age": 52,
  "bornMonthYear": "February 1974",
  "birthYear": 1974,
  "deceased": false,
  "aliases": ["John L Smith JR", "J L Smith"],
  "currentAddress": {
    "fullAddress": "1200 Sample Ave, Apt 4, Alexandria, VA 22304-0001",
    "street": "1200 Sample Ave, Apt 4",
    "city": "Alexandria",
    "state": "VA",
    "zip": "22304-0001",
    "dateRange": "Jan 2006 - Oct 2026",
    "addressUrl": "https://www.usphonebook.com/address/1200-sample-ave-apt-4_alexandria-va"
  },
  "pastAddresses": [
    {
      "fullAddress": "500 Example Blvd, Apt 12, Austin, TX 78753-0002",
      "street": "500 Example Blvd, Apt 12",
      "city": "Austin",
      "state": "TX",
      "zip": "78753-0002",
      "dateRange": "Oct 2019 - Sep 2022",
      "addressUrl": "https://www.usphonebook.com/address/500-example-blvd-apt-12_austin-tx"
    }
  ],
  "phones": [
    { "number": "(512) 555-0143", "type": "Voip", "carrier": "Example Cable Llc", "lastReported": "October 2026", "isPrimary": true },
    { "number": "(512) 555-0178", "type": "Landline", "carrier": "Example Telephone Company", "lastReported": "April 2021", "isPrimary": false }
  ],
  "primaryPhone": "(512) 555-0143",
  "emails": ["john.sample@example.com", "jls.sample@example.net"],
  "relatives": [{ "name": "Adam Smith", "profileUrl": "https://www.usphonebook.com/adam-smith/UxExampleIdForAdamSmith0000cD" }],
  "associates": [{ "name": "Ella Sample", "profileUrl": "https://www.usphonebook.com/ella-sample/UxExampleIdForEllaHill00000eF" }],
  "workplaces": [{ "jobTitle": "Payroll Analyst", "employer": null, "location": "Austin, TX", "industry": "Government", "current": true }],
  "matchType": null,
  "detailsFetched": true,
  "searchUrl": "https://www.usphonebook.com/john-smith/tx/austin",
  "source": "usphonebook",
  "searchedAt": "2026-11-13T15:35:48.009Z",
  "scrapedAt": "2026-11-13T15:35:49.598Z",
  "query": { "searchMode": "name", "firstName": "John", "lastName": "Smith", "city": "Austin", "state": "TX", "inputGiven": "John Smith, Austin, TX" },
  "Search Option": "Name Search",
  "Input Given": "John Smith, Austin, TX"
}
```

### Key Output Fields

#### Identity

`fullName` keeps the middle name the search results show; `firstName` and `lastName` come from the profile. `bornMonthYear` and `birthYear` appear when the profile lists them.

#### Phones

`phones[]` lists every number on the profile, current number first (`isPrimary: true`), each with line type, carrier and the month it was last reported.

#### Emails

`emails[]` holds every address the profile lists, as plain lowercase text.

#### Addresses

`currentAddress` and `pastAddresses[]` carry the street, city, state, ZIP+4 and `dateRange` ("Oct 2019 - Sep 2022"). The same address can appear more than once in the history with different dates.

#### People network

`relatives[]` (all of them, not only the first nine the page shows) and `associates[]`, each with a profile link you can feed back in as a start link.

### FAQ

#### What do I get on the free Apify plan?

One search per run and up to 25 people from the search results (name, age, city and state, past cities, relatives), with contact details partly hidden. Full profiles with phones, emails and street addresses need a paid Apify plan.

#### How am I charged?

Per person row saved to the dataset, plus a full-details charge for each person whose full profile was read. Searches that find nobody add no rows. With full details off, only the rows are charged.

#### Why do some rows have no phones?

The person's full profile could not be read after several retries, so the row holds the search-results summary and `detailsFetched` is `false`. The run's status message says how many.

#### Why did a search return fewer people than I asked for?

The site lists at most 250 people for one name search, the actor leaves out lookalike names and (with a state) people who never had an address in that state, and in a batch each search keeps 3 people unless you set `maxItemsPerSearch`. The run's status message says how many people were left out for their location.

#### Can I search a whole state?

Yes: leave the city empty. Leave both empty to search the whole country.

#### Can I search by address?

Not at the moment: USPhoneBook's address pages no longer list residents.

#### Which links can I paste?

Name search pages (any page number), phone lookup pages and person profiles from usphonebook.com.

#### Can I get private or paywalled data?

No. The actor reads the public pages anyone can open without an account.

### Support

Found a bug or have a feature request? Open an issue on the actor's Issues tab in the Apify Console, or email **muhameddidovic@gmail.com**.

### Additional Services

Need a custom export shape, monitoring on a schedule, or the same data from another people-search site? I do tailored work. Write to **muhameddidovic@gmail.com**.

### Explore More Scrapers

If you found this useful, you might also like:

- [**FastPeopleSearch Scraper**](https://apify.com/memo23/fastpeoplesearch-scraper): the same kind of person records from FastPeopleSearch.com
- [**TruePeopleSearch Scraper**](https://apify.com/memo23/truepeoplesearch-people-search-scraper): person records from TruePeopleSearch.com

Full list at [apify.com/memo23](https://apify.com/memo23).

### 🤖 For AI Agents & LLM Apps

Compact reference for AI agents calling this actor through the [Apify MCP server](https://mcp.apify.com) or the Apify API (actor: `memo23/usphonebook-scraper`).

**Purpose:** US people search on USPhoneBook.com by name (state and city optional) or phone number; returns one row per person with phones (type, carrier), emails, dated address history, relatives and associates.

**Minimal input:**

```json
{ "firstName": "John", "lastName": "Smith", "state": "TX", "maxItems": 5 }
```

**Batch input:**

```json
{ "searches": [{ "firstName": "Jane", "lastName": "Doe", "state": "FL" }], "phoneNumbers": ["8035550199"], "maxItemsPerSearch": 3, "maxItems": 20, "flattenedOutput": true }
```

**Output:** one dataset row per person: `fullName`, `age`, `birthYear`, `phones[]` (`number`, `type`, `carrier`, `lastReported`, `isPrimary`), `primaryPhone`, `emails[]`, `currentAddress`, `pastAddresses[]`, `relatives[]`, `associates[]`, `matchType` (phone lookups), `detailsFetched`, `query.inputGiven`.

**Behaviors an agent should know:**

- Always set `maxItems`. In a batch, each search keeps 3 people unless `maxItemsPerSearch` says otherwise.
- `startUrls` replaces every search; `phoneNumbers` and `searches` replace the single name fields.
- `state` takes a two-letter code; a city needs a state.
- Expect a few seconds per person with full details on.

***

### ⚠️ Disclaimer

This Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by USPhoneBook.com or its operators. All trademarks mentioned are the property of their respective owners.

The scraper reads only publicly available people-search pages: no logged-in pages, paid features, or content behind any login wall. People-search data is sensitive: users are responsible for making sure their use complies with USPhoneBook.com's Terms of Service, the Fair Credit Reporting Act (this actor is not a consumer reporting agency, and its output must not be used for FCRA-regulated purposes such as employment, credit, insurance or tenant screening), the TCPA and Do-Not-Call rules when contacting phone numbers, applicable data-protection law (CCPA and other state privacy laws, GDPR), and their own organization's obligations.

***

### SEO Keywords

usphonebook scraper, usphonebook.com scraper, scrape usphonebook, usphonebook API, us phone book lookup, people search scraper, reverse phone lookup API, phone number owner lookup, skip tracing tool, skip tracing data, people finder API, find phone number by name, email finder people search, address history data, relatives and associates data, US public records scraper, contact enrichment, real estate lead generation, property owner contact lookup, fastpeoplesearch alternative

# Actor input Schema

## `firstName` (type: `string`):

First name of the person you are looking for.

## `lastName` (type: `string`):

Last name of the person you are looking for.

## `state` (type: `string`):

US state that narrows the search. Leave empty to search the whole country.

## `city` (type: `string`):

City that narrows the search further. Needs a state.

## `matchLocation` (type: `boolean`):

On by default. USPhoneBook mixes people from other states into a state or city search; with this on, anyone with no current or past address in the state you chose is left out and not charged. Turn it off to get every person the site lists.

## `phoneNumbers` (type: `array`):

US phone numbers to look up, one per line, in any format (e.g. (512) 382-7193 or 5123827193). Each returns the number's current owner and earlier owners.

## `searches` (type: `array`):

Many name searches in one run, one object each, with firstName, lastName and optionally state and city (an object with only phone is a phone lookup). Example: \[{"firstName":"Jane","lastName":"Doe","state":"FL","city":"Miami"},{"phone":"5123827193"}]. Up to 1,000 per run on paid plans, 1 on the free plan.

## `maxItemsPerSearch` (type: `integer`):

How many people to keep from each search. When you run more than one search and leave this empty, each search keeps 3, so one common name cannot use up the whole run.

## `startUrls` (type: `array`):

Links such as https://www.usphonebook.com/john-smith/tx/austin, https://www.usphonebook.com/512-382-7193 or a person's profile link. Name search links continue onto the following results pages.

## `maxItems` (type: `integer`):

The most people this run returns, across all searches. Up to 5,000 per run (25 on the free plan).

## `openProfiles` (type: `boolean`):

On by default: opens every person's profile for all phone numbers (with line type, carrier and last report date), emails, street addresses with dates, birth month, aliases and associates. Turn off to get only the search-results summary (name, age, city, past cities, relatives), which is faster and has no details charge.

## `flattenedOutput` (type: `boolean`):

Adds CRM-style columns to every row (Phone-1 to Phone-5 with type and carrier, Email-1 to Email-5, Street Address, Person Link) so a CSV export drops straight into a spreadsheet. The nested fields stay on the row.

## `maxConcurrency` (type: `integer`):

How many pages are loaded at the same time. The default of 5 suits most runs.

## Actor input object example

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "state": "TX",
  "city": "Austin",
  "matchLocation": true,
  "maxItems": 10,
  "openProfiles": true,
  "flattenedOutput": false,
  "maxConcurrency": 5
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset of person records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "firstName": "John",
    "lastName": "Smith",
    "state": "TX",
    "city": "Austin"
};

// Run the Actor and wait for it to finish
const run = await client.actor("memo23/usphonebook-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "firstName": "John",
    "lastName": "Smith",
    "state": "TX",
    "city": "Austin",
}

# Run the Actor and wait for it to finish
run = client.actor("memo23/usphonebook-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "firstName": "John",
  "lastName": "Smith",
  "state": "TX",
  "city": "Austin"
}' |
apify call memo23/usphonebook-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,memo23/usphonebook-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/7C8tFTg1gGYuCnwor/builds/SCfc9eEHLGq5bo9TY/openapi.json
