Identity Resolution API - Reverse Email and Phone Lookup

Turn a single identifier into the person behind it. Give it an email address, a phone number, a name, a username, a social profile URL or a VIN, and get back one flat row per person: names, emails, phones, addresses, jobs, education, social profiles, gender, date of birth and a confidence score on the match itself.

What this actor does

• Resolves eight kinds of identifier. Reverse email lookup, reverse phone lookup, name search, username or user id, social profile URL, VIN, a combined lookup that reads several lists row by row so one row is one person, and a follow-up search that expands a candidate from an earlier run.
• Tells you how confident the answer is. Every row carries a match score. A score of 1 means the provider resolved your search to a single person; anything lower means it returned candidates, and each candidate row is flagged with isPossibleMatch so a confident match is never quietly mixed in with a guess.
• Lets you not pay for the wrong answer. The provider evaluates a match requirement before it charges, so a search that comes back without the field you actually needed returns empty and is not billed. Ask for an email, or a mobile phone, or a work email and a job, and only matching answers cost anything. This is the single most important setting in the input.
• Finds data you do not already have. Switch on new data only, and a requirement of email means an email other than the one you searched with. This is how you expand a contact record rather than pay to be told what you already knew.
• Expands ambiguous answers on request. When the provider returns candidates rather than one person, each candidate carries its own search pointer. Turn on expansion and the actor follows those pointers to pull full records, up to a ceiling you set. It is off by default because each expansion is a second billable search.
• Refuses a guess when you cannot afford one. Confident single match mode returns the best high ranking person or nothing at all, never a candidate list, which is what automated enrichment needs.
• Shows its work. Switch on the source layer and every row carries the sources behind it, with source name, category, domain and origin URL, so an answer can be audited rather than trusted.
• Handles pointers that are too long for a URL. A search pointer is roughly two kilobytes of hex. Sent on a query string it comes back as HTTP 414, so follow-up searches go out in a form encoded body instead, which is what the provider documents.
• Tells a rate limit from a spent quota. Both arrive as HTTP 403 from this provider. The per second limit clears by itself and is retried with backoff; a used-up daily, weekly or monthly quota stops the run with what it has rather than burning retries on something waiting will not fix.
• Never charges for a miss. Only rows carrying a resolved person are billed.

Input

Field	What it does
mode	Email, phone, name, combined, username, profile URL, VIN or search pointer.
emails, phones, names, addresses	The identifiers to resolve. In combined mode they are read row by row.
usernames, profileUrls, vins, searchPointers	The other identifier types.
country, state, city	Narrow every search in the run. Biggest single lever on a name search.
matchRequirements	Fields the answer must contain, or it is free.
matchRequirementsJoin	Require all of them, or any one of them.
matchRequirementsNewDataOnly	Only count data that was not in your query.
sourceCategoryRequirements	Source types the answer must draw on, or it is free.
topMatch	Return a confident single person or nothing.
minimumMatch	Provider side confidence floor, 0 to 100.
minimumProbability	How sure the provider must be before including inferred data.
inferPersons	Allow people assembled purely by inference.
liveFeeds	Query live sources as well as the index.
hideSponsored	Leave out results behind a third party paywall.
showSources	Return the source layer: none, matching, or all.
expandPossiblePersons, maxExpansionsPerSearch	Follow candidate pointers into full records.
minMatchScore, requireEmail, requirePhone, requireJob, requireSocialProfile, skipPossibleMatches	Local filters on the rows.
skipNotFound	Leave unresolved searches out of the dataset.
requestsPerMinute	Pace the run under your plan's rate limit.
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": "email",
  "query": "jane.doe@example.com",
  "isPossibleMatch": false,
  "matchScore": 1,
  "personId": "3b95e0c1-abca-4240-8e89-0da7473f8580",
  "searchPointer": "e43a4955834bb50c5478ba5eb38db",
  "isInferred": false,
  "fullName": "Jane A Doe",
  "firstName": "Jane",
  "middleName": "A",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "emailType": "work",
  "emails": ["jane.doe@example.com", "jane@personal.example"],
  "phone": "+1 206-555-0100",
  "phoneType": "mobile",
  "address": "100 Main Street, Seattle, Washington",
  "city": "Seattle",
  "state": "WA",
  "country": "US",
  "jobTitle": "Director of Engineering",
  "organization": "Example Corp",
  "industry": "Software",
  "school": "University of Washington",
  "gender": "female",
  "dateOfBirth": "1985-06-18",
  "socialProfiles": ["https://www.linkedin.com/in/janedoe"],
  "usernames": ["janedoe"],
  "visibleSources": 5,
  "availableSources": 78,
  "error": null
}

Rows also carry sources when the source layer is on, availableData with the provider's own count of what it holds for the search, and raw, the untouched person object, so nothing is lost in flattening.

Frequently asked questions

What is an identity resolution API?

It is an API that takes a fragment of identity, one email address, one phone number, one username, and returns the single real person that fragment belongs to, merged from many sources into one record with a confidence score attached. It is the difference between a directory lookup, which returns rows that mention your search term, and identity resolution, which returns a person.

How do I do a reverse email lookup?

Run the actor in email mode with a list of addresses. Each address is resolved to the person who owns it, and the row carries their name, other email addresses, phone numbers, postal addresses, jobs and social profiles. Set a match requirement of name or job if a row without those is not worth paying for.

How do I find someone's other email addresses or phone numbers?

Search by the identifier you already have, set the match requirement to email or phone, and switch on new data only. The provider then only charges when the answer contains an address or number other than the one you searched with, which is exactly the case you were paying to find.

What is the difference between a person response and a possible persons response?

A person response means the provider resolved your search to one individual, and it is the fuller of the two records. A possible persons response means it could not, and returns up to fifty thinner candidate records instead, each with its own match score and search pointer. Every candidate is written as its own row with isPossibleMatch set to true. Turn on expansion to follow their pointers into full records, or turn on confident single match mode to refuse candidates entirely.

What is a search pointer?

A token the provider returns with every person and candidate that stands for that exact search. Feed it back in search pointer mode and you get the full record for that specific person without having to describe them again. It is also how you check for updates on a record you already have.

How do I stop paying for searches that miss?

Use matchRequirements. The provider checks the condition before billing, so a search whose answer does not contain the field you required returns empty and free. The local filters in this actor, such as requireEmail, run after the provider has answered and charged, so they only trim the dataset. Use them for tidiness and the match requirement for cost.

Can I search by name alone?

Yes, but narrow it. A common name with no location returns candidates rather than a person nearly every time. Set a country, and a state or city where you know one, and consider combined mode if you also hold an email, a phone or an address for that person: a name plus one more identifier is usually the difference between a candidate list and a confident match.

Do I need my own API key?

Yes. This actor does not include data access. You use your own API key from Pipl, which is the provider whose identity resolution API this actor calls. Your own plan, quota and terms apply, including which data fields your key is entitled to. Paste the key into the apiKey field, where it is stored as an Apify secret, or supply it as the DATA_API_KEY environment secret.

What happens when a search matches nobody?

The row is written with found: false and an error giving the reason, together with any warnings the provider returned, and the run continues to the next input. A no match answer is HTTP 200 with a persons count of zero at this provider, not an error, so it is treated as a result. Misses are never charged for. Set skipNotFound to true to leave them out of the dataset entirely.

How much does a run cost?

Pricing is pay per result: you are charged for each person resolved into the dataset, and never for searches that matched nobody, for rows dropped by the filters, or for duplicates. Apify platform usage is included in the per-result price. Note that an ambiguous search can return several candidate rows, and that expanding a candidate produces a second charged row. Your own API provider's quota is separate and billed by them.

Keyword map

identity resolution API, reverse email lookup API, reverse phone lookup API, people search API, person lookup by email, email to person, phone to person, social profile lookup, username lookup API, LinkedIn URL lookup, contact enrichment API, person enrichment, identity verification data, match score, confidence score, people data API, background data API, VIN owner lookup, contact data waterfall, lead enrichment