People Search API - Reverse Phone, Email and Address

Start from a phone number, an email address, a name, a street address or a username, and get back the people behind it, one row per person.

What this actor does

• Runs six searches over one key. Reverse phone, reverse email, name search, address search, username search, and a full record lookup by person identifier. All six write to the same dataset shape, so a mixed set of runs still reads as one table.
• Writes one row per person, not one row per search. These searches are one to many: a phone number may have had four owners, a name search can match sixty people. Burying that in nested JSON would make the output unusable as a table, so a row here is one entity found, and the search that produced it is carried on every row.
• Separates the current holder from the previous ones. A reverse search returns everyone the provider has ever associated with an identifier. The person who had the number in 2011 is not the person who has it now, so that is its own column with its own filter rather than being silently resolved one way or the other.
• Returns the full person record. Names and aliases, age, month and year of birth, deceased status, current and historical addresses, phone numbers, email addresses, relatives, social profiles, usernames, work history and schools.
• Chains a search into a full record. Every person comes back with an identifier, and the person identifier search takes that identifier and returns the complete record, including certifications, languages and historical records. Search wide first, then pull the full record for the handful you actually care about.
• Reads addresses as properties. An address search returns the property itself: type, bedrooms, bathrooms, year built, market valuation with a confidence score, county, coordinates, nearby schools, and the residents and owners with their own person identifiers so you can look each one up.
• Follows result pages properly. The two searches that page do so by opaque token, not by page number, and the token sits at a different depth depending on the route. Both locations are read, and a token the provider hands back twice stops the loop rather than spinning on it.
• Refuses searches that cannot work, before they cost anything. A number that is not ten digits, an address with no city, a name search with no name: all refused locally and recorded as refusals rather than paid for.
• Says what a forbidden response actually means. This provider checks the key at its gateway before it looks at the request, so a wrong key answers with a bare forbidden that says nothing about keys. The credential error here says so, because otherwise it reads as a data permissions problem rather than a typo.
• Never charges for a miss. Only rows carrying a found person, profile or property are billed.

Input

Field	What it does
mode	Which search to run.
queries	What to look up, one per line or as JSON objects.
ageMin	Narrow a name search, and drop younger people.
ageMax	Narrow a name search, and drop older people.
distance	Search radius in miles around a city or address.
includePossibleMatches	Also return partial name matches.
followPages	Keep asking for the next page of a paged search.
currentOwnersOnly	Keep only who has the number or address now.
minConfidenceScore	Keep only matches at this confidence or better.
excludeDeceased	Drop records marked deceased.
excludeCompanies	Drop business rather than person records.
requirePhone	Keep only people with a phone number.
requireEmail	Keep only people with an email address.
requireAddress	Keep only people with a street address.
states	Keep only these US states.
networks	Keep only these social networks.
requestsPerMinute	Pace the run under your plan's rate limit.
skipNotFound	Leave misses and refusals out of the dataset.
maxResults	Hard cap on rows, and therefore on spend and run time.
apiKey	Your own API key. Stored as a secret.

Example output

{
  "found": true,
  "mode": "phone",
  "query": "2125550100",
  "personId": "p1234567890",
  "fullName": "Jane A Doe",
  "firstName": "Jane",
  "middleName": "A",
  "lastName": "Doe",
  "allNames": ["Jane A Doe", "Jane Smith"],
  "age": 41,
  "dobMonth": 6,
  "dobYear": 1985,
  "isDeceased": false,
  "isCompany": false,
  "isCurrentOwner": true,
  "confidenceScore": 0.94,
  "primaryPhone": "2125550100",
  "phones": ["2125550100", "9175550188"],
  "phoneCount": 2,
  "primaryEmail": "jane.doe@example.com",
  "emails": ["jane.doe@example.com"],
  "street": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zip": "10001",
  "addressCount": 3,
  "addresses": ["123 Main St, New York, NY, 10001", "44 Oak Ave, Newark, NJ, 07102"],
  "relatives": ["John Doe", "Mary Smith"],
  "socialProfiles": ["https://www.linkedin.com/in/example"],
  "workHistory": ["Director at Example Corp"],
  "schools": ["State University"],
  "totalMatches": 4,
  "error": null,
  "raw": { }
}

Frequently asked questions

What does a row represent?

One person, one social profile, or one property, depending on the search. Not one search. A reverse phone search on a number with four historical owners produces four rows, and a name search matching sixty people produces sixty. This matters when you set the result cap, because a list of twenty names can easily produce several hundred rows.

What is the difference between a current owner and the other results?

A reverse phone or address search returns everyone the provider has ever associated with that identifier, not just whoever holds it today. Numbers get recycled and people move, so the person who had the number in 2011 shows up alongside the person who has it now. The isCurrentOwner column tells them apart, and currentOwnersOnly filters to just the present holder. Which you want depends entirely on the job: skip tracing usually wants the history, outreach usually does not.

How do I go from a search result to a full record?

Every person comes back with a personId. Feed those identifiers into a second run in person identifier mode, and each one returns the complete record, which is deeper than what a search result carries: certifications, languages, historical records and the full address and employment history. The efficient pattern is to search wide, filter down to the people you actually care about, then pull full records for only those.

Which search should I use to find someone by name?

Name search, and give it more than the name. A bare name in a large country returns a lot of people who are not the one you want. Add a city and state, or an age range, or a relative's name; those three are what actually narrow it. If a precise search returns nothing, turn on possible matches and sift, rather than assuming the person is absent.

Why was my phone number refused before it was sent?

This provider's reverse phone search takes a ten digit US number. A number written with the North American country code in front is the same number, so the code is stripped and the search runs. Anything that is not ten digits after that is refused locally, because the provider charges per request whether or not it can answer, and a nine digit or fifteen digit string cannot be a US number. Refusals are written to the dataset with the reason, so you can see exactly which inputs were skipped.

What does an address search return?

The property, not just the coordinates. Type, bedrooms, bathrooms, year built, a market valuation with its own confidence score, county, latitude and longitude, and nearby schools, plus the residents and owners with their person identifiers so each one can be looked up. An address with several units returns one row per property.

Why do I keep getting a forbidden response?

Almost always the key. This provider checks the credential at its gateway before it routes the request, so a missing, mistyped, or not-yet-enabled key produces a bare forbidden with no explanation, and so does a request to a path that does not exist. Since the two are indistinguishable from outside, the credential error from this actor says so plainly rather than guessing. Check the key first, and check that the people search product is enabled on your account.

Does this search outside the United States?

The searches here are built around US data: the reverse phone search takes ten digit US numbers, and the address search takes a US state. Email and username searches are less geographically bound, since profiles are global. If your list is international, the email and username searches are the two worth running.

Do I need my own API key?

Yes. This actor does not include data access. You use your own API key from Spokeo, which is the provider whose people search API this actor calls, taken from your provider account and pasted into the apiKey field, where it is stored as an Apify secret. Your own plan, quota and terms apply.

Is there anything I should know before using people data?

Yes. Personal data of this kind is regulated in most places, and the provider's own terms restrict what it may be used for. In particular, consumer report uses such as employment, tenancy, insurance and credit decisions are typically prohibited unless you hold a specific permissible purpose. This actor is a transport for your own licensed access, and the responsibility for lawful use sits with you and your agreement with the provider.

What happens when a search finds nobody?

That is a result worth keeping: a number nobody is associated with is an answer. Searches that matched nobody are written with found: false and are never billed, as are entries refused before they were sent. Set skipNotFound to true to leave them out entirely. A search whose matches were all removed by your filters is not counted as a miss, because it did find people.

How much does a run cost?

Pricing is pay per result: you are charged for each person, profile or property written to the dataset, and never for searches that matched nobody, for locally refused entries, for rows dropped by the filters, or for duplicates. The same person returned by two different searches in one run is charged once. Apify platform usage is included in the per-result price. Your own provider quota is separate and billed by them.

Keyword map

people search API, reverse phone lookup API, reverse email lookup, caller ID lookup, phone number to name, email to person, email to social profiles, username search API, social profile lookup, name search API, find a person by name, address lookup API, reverse address search, property records API, resident lookup, skip tracing API, contact enrichment API, identity data API, relatives lookup, background data API, people data enrichment, person identifier lookup, work history lookup, genealogy data API, debt collection skip trace, tenant screening data