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

{
  "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.