# People Search API - Phone, Email and Address Identity Data (`nabeelbaghoor/people-search-identity-data-api`) Actor

Look up people by name, phone, email or street address and get verified phone numbers, email addresses, address history, relatives and associates. Also covers reverse phone, caller ID, business records, employment records and domain registrants. Pay per result. Bring your own API key.

- **URL**: https://apify.com/nabeelbaghoor/people-search-identity-data-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Developer tools, Lead generation
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$15.00 / 1,000 results

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## People Search API - Phone, Email and Address Identity Data

Look up a person by name, phone number, email address or street address and get back the phone numbers, email addresses, address history, relatives and associates on record for them. The same actor covers reverse phone lookup, caller identification, business and corporation records, self reported employment records, and domain registrant records. One flat row per record.

### What this actor does

- **Fills in a partial contact record.** Contact enrichment takes any two of a name, a phone number, an address and an email address and returns the top matching person with their top five phone numbers, email addresses and addresses. The lists are read row by row, so a spreadsheet of half complete leads goes in as it stands.
- **Works a phone number in both directions.** Caller identification returns the single best owner of a number. Reverse phone returns every owner, each as its own row with their own addresses, which is what you want when a number has changed hands.
- **Finds who lives or owns at an address.** Address lookup returns the people associated with a property, and can be narrowed to current owners or current residents.
- **Searches rather than only matching.** Person search takes a name plus whatever else you have, pages through every match, and returns full address history with first and last reported dates, alternate names, relatives, associates and indicators showing which other record types exist for that person.
- **Covers businesses and employment too.** Business search returns corporation, trading name and tax id records. Workplace search returns self reported employment, filterable by industry, department, job title, seniority and skill, with the option to include past positions. Domain search returns registrant name and contact details for a domain.
- **Reads both of the provider's response dialects.** The enrichment products answer in one shape and the search products in another. Every row is flattened to the same leading columns, so results from different products stack in one table.
- **Keeps the ranked detail as well as the best answer.** The provider ranks phone numbers, addresses and email addresses. The top one of each is lifted into a leading column and the full ranked arrays are kept alongside, because the second number is the one you call when the first is dead.
- **Never charges for a miss.** Only rows carrying a resolved record are billed.

### Compliance note

This is regulated consumer data. Identity records must not be used to make decisions about credit, insurance, employment, tenancy or any other permissible purpose covered by consumer reporting law unless your own agreement with the provider explicitly allows it. Your account governs what you may use these records for, and this actor cannot and does not check that for you.

### Input

| Field | What it does |
| --- | --- |
| `mode` | Which of the twelve products to run. |
| `fullNames` | Names to look up, read row by row with the lists below. |
| `phones`, `emails`, `addresses` | The other identifiers to look up or match on. |
| `addressMatchType` | Current owners, current residents, or top associated people. |
| `dob`, `age`, `ageRange` | Narrow a common name down to one person. |
| `personIds` | Look up provider person ids directly. |
| `includes`, `filterOptions` | Sections and filters your account has enabled. |
| `maxAddressYears`, `maxPhoneYears` | Drop stale addresses and numbers. |
| `teaserOnly` | Masked, cheaper person search results. |
| `businessName`, `businessType`, `taxId`, `county` | Business search criteria. |
| `city`, `state`, `zip`, `country` | Location criteria for workplace and domain search. |
| `industry`, `department`, `jobTitle`, `jobLevel`, `skill` | Workplace search criteria. |
| `workplaceScope` | Current positions only, or every position on record. |
| `freeFormSearch` | Single free text query for domain search. |
| `resultsPerPage` | How many records each search request asks for. |
| `requestsPerMinute` | Pace the run under your plan's rate limit. |
| `skipNotFound` | Leave unresolved inputs out of the dataset. |
| `maxResults` | Hard cap on rows, and therefore on spend and run time. |
| `clientId`, `apiKey` | Your access profile name and password. Both stored as secrets. |

### Example output

```json
{
  "found": true,
  "mode": "contactEnrich",
  "query": "John Smith",
  "personId": "G-000000000000000000",
  "fullName": "John Z Smith",
  "firstName": "John",
  "middleName": "Z",
  "lastName": "Smith",
  "age": 55,
  "dob": "2/1975",
  "isDeceased": false,
  "phone": "(555) 555-5555",
  "phoneType": "landline",
  "phoneIsConnected": true,
  "email": "john.smith@example.com",
  "emailIsValidated": true,
  "emailIsBusiness": false,
  "address": "1234 Apple Ct, Liberty, OH 45044",
  "city": "Liberty",
  "state": "OH",
  "zip": "45044",
  "addressFirstReported": "3/25/2005",
  "addressLastReported": "7/1/2023",
  "relatives": [
    { "personId": "G-000000000000000001", "name": { "firstName": "Carol", "lastName": "Smith" } }
  ],
  "identityScore": 90,
  "error": null,
  "raw": { }
}
```

### Frequently asked questions

#### What is a people search API?

A people search API resolves an identifier you already hold, such as a name, a phone number, an email address or a street address, into the full identity record behind it: the person's name and age, the phone numbers and email addresses on record for them, where they have lived and when each address was last reported, and the relatives and associates linked to them. This actor exposes twelve such products as actor input and writes one flat row per record, so a list of partial leads goes in and a table of complete contact records comes out.

#### What is the difference between caller ID and reverse phone lookup?

Caller identification returns the single highest ranked owner of a phone number, with their current address, which is what a call centre screen needs. Reverse phone returns every person the provider associates with that number, each with their own linked addresses, and pages through them. Use caller identification when you need one answer fast and reverse phone when the number may have changed hands, since a reassigned mobile can carry two or three owners across a few years and only the full list shows you that.

#### What do the plus variants add, and are they worth it?

Each of contact enrichment, caller identification and email lookup has a plus variant. The plus variants return everything the standard one does plus a persistent person id, a partial date of birth, the top associates with their own ids, extra property detail per address including owner occupancy and coordinates, and around fifteen consumer insight fields such as estimated income, marital status, occupation, education and home value. They cost more per lookup on the provider side, which is why they are separate modes here rather than a checkbox: switching to plus is a spending decision, so it should be a deliberate one.

#### How do I narrow a search down to one person?

Add a second identifier. A first and last name alone returns thousands of matches for a common name; adding a city and state, a date of birth or an address cuts that to a handful. Date of birth is the sharpest single filter, and `maxAddressYears` helps a lot too, since it stops decades of address history burying the current one. If you are working through a large match set, keep the person ids from the first pass and look those up directly on the second: an id resolves to exactly one person.

#### Can it return employment and business records?

Yes. Workplace search covers self reported employment, filterable by business name, person name, location, industry, department, job title, seniority and skill, and `workplaceScope` decides whether you get current positions only or every position on record. Past positions are what tell you a contact has moved on since the record you are holding. Business search covers corporation, trading name and tax id records including bankruptcy, judgment and lien data, and links a business back to the people behind it. Domain search returns the registrant name and contact details for a domain.

#### Why does this actor need two credentials instead of one API key?

Because this provider issues a pair: an access profile name and an access profile password, sent as two separate headers on every request. Put the name in `clientId` and the password in `apiKey`. Both are stored as secrets and neither is ever written to a log. You can also supply them as the `DATA_API_CLIENT_ID` and `DATA_API_KEY` environment secrets. A request with only one half is rejected before it reaches any product.

#### Do I need my own API key?

Yes. This actor is bring your own key: it calls the identity data API with credentials from your own account, so your plan governs your entitlements, your rate limit and, importantly here, what you are permitted to use the data for. Products your access profile is not entitled to will refuse the request rather than silently returning less. The actor's own charge is separate and is per row resolved, and rows that resolved to nothing are never charged for.

### Keyword map

People search API, identity data API, reverse phone lookup API, caller identification API, contact enrichment, email to person lookup, address to resident lookup, skip tracing data, relatives and associates, employment records API, business records search, domain registrant lookup.

# Actor input Schema

## `mode` (type: `string`):

The enrichment products take one identifier and return the best matching person. The plus variants of each return the same data plus a person id, partial date of birth, associates, per address property detail and consumer insight fields, and cost more per lookup. The search products take criteria and page through every match.

## `fullNames` (type: `array`):

Names to look up, one per line. The last word is treated as the surname and anything between as the middle name. Contact enrichment reads this list row by row alongside the phone, email and address lists, so row one of each describes the same person. The search products use the first name in the list as their criteria.

## `phones` (type: `array`):

Phone numbers, one per line, in any format. Punctuation is stripped and a leading country code is removed from a ten digit number before the request.

## `emails` (type: `array`):

Email addresses, one per line. An address pasted inside a longer string is extracted before the request.

## `addresses` (type: `array`):

Street addresses, one per line, written as street, then city and state, for example 1234 Main Street, Los Angeles, CA. Everything before the first comma is read as the street and the rest as the city, state and postcode.

## `addressMatchType` (type: `string`):

For address lookups, whether to return the current owners of the property or its current residents. Leave empty to get the top people associated with the address instead.

## `dob` (type: `string`):

Date of birth as mm/dd/yyyy. Adding this to a common name is the single most effective way to cut a person search down to one person.

## `age` (type: `integer`):

Exact age, when you know it but not the date of birth.

## `ageRange` (type: `string`):

Age range as min-max, for example 35-45. Person search only.

## `personIds` (type: `array`):

Provider person ids to look up directly, one per line. These come back on earlier rows, so a broad search followed by a targeted lookup of the ids you kept is the cheapest way to work a large match set.

## `includes` (type: `array`):

Which sections the person search should return, one per line, such as Addresses or PhoneNumbers. These are enabled per account by your provider, so an unavailable section is simply absent from the response rather than an error. Leave empty for the account default.

## `filterOptions` (type: `array`):

Provider filter options for the person search, one per line, such as IncludeLowQualityAddresses. Like sections, these are enabled per account.

## `maxAddressYears` (type: `integer`):

Drop addresses last reported more than this many years ago. This is how you stop a record from twenty years of history burying the current address.

## `maxPhoneYears` (type: `integer`):

Drop phone numbers last reported more than this many years ago.

## `teaserOnly` (type: `boolean`):

Run the person search in teaser mode, which returns masked and limited records rather than full ones. This is the variant intended for logged out users of a consumer facing product, and it is cheaper per search.

## `businessName` (type: `string`):

Business name for the business, workplace and domain searches.

## `businessType` (type: `string`):

Business type for the business search.

## `taxId` (type: `string`):

Tax id or FEIN for the business search.

## `county` (type: `string`):

County for the business search.

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

City for the workplace and domain searches.

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

Two letter state code for the workplace and domain searches.

## `zip` (type: `string`):

Five digit postcode for the workplace and domain searches.

## `country` (type: `string`):

Two letter country code for the domain search, such as US or CA.

## `industry` (type: `string`):

Industry for the workplace search. The accepted values are served by the provider's own drilldown search and are enabled per account.

## `department` (type: `string`):

Department for the workplace search.

## `jobTitle` (type: `string`):

Job title for the workplace search.

## `jobLevel` (type: `string`):

Seniority level for the workplace search.

## `skill` (type: `string`):

Skill for the workplace search.

## `workplaceScope` (type: `string`):

Whether the workplace search returns only current positions or every position on record. Past positions are what tell you someone has moved on since the record you are holding.

## `sortDirection` (type: `string`):

Sort direction for the workplace search.

## `freeFormSearch` (type: `string`):

A single free text query for the domain search, such as a company name.

## `resultsPerPage` (type: `integer`):

How many records each search request asks for. Larger pages mean fewer requests, and a page that comes back short is treated as the last one.

## `requestsPerMinute` (type: `integer`):

Pace the run under your plan's rate limit. Lower this if the provider starts refusing requests.

## `skipNotFound` (type: `boolean`):

Leave inputs that resolved to nothing out of the dataset. They are kept by default, because knowing which inputs the provider has nothing on is what makes a run auditable. Unresolved rows are never charged for either way.

## `maxResults` (type: `integer`):

Hard cap on rows, and therefore on spend and run time.

## `clientId` (type: `string`):

The first half of your credential: the access profile name from your provider account. This provider issues a name and a password rather than a single key, and both are required. Stored as a secret. You can also supply it as the DATA\_API\_CLIENT\_ID environment secret.

## `apiKey` (type: `string`):

The second half of your credential: the access profile password from your provider account. Stored as a secret and never written to a log. You can also supply it as the DATA\_API\_KEY environment secret instead.

## Actor input object example

```json
{
  "mode": "contactEnrich",
  "fullNames": [
    "John Smith"
  ],
  "addressMatchType": "",
  "teaserOnly": false,
  "workplaceScope": "",
  "sortDirection": "",
  "resultsPerPage": 10,
  "requestsPerMinute": 300,
  "skipNotFound": false,
  "maxResults": 100
}
```

# Actor output Schema

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

People, businesses, employment records and domain registrants, one row each.

# 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 = {
    "fullNames": [
        "John Smith"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/people-search-identity-data-api").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 = { "fullNames": ["John Smith"] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/people-search-identity-data-api").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 '{
  "fullNames": [
    "John Smith"
  ]
}' |
apify call nabeelbaghoor/people-search-identity-data-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/people-search-identity-data-api"
        }
    }
}

```

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/YbIWvYWEwkGASKHlr/builds/EKX7V5HF6owTkXi5j/openapi.json