People Search API Guide: Avoid Wrong-Person Matches

A people search API can return a technically valid response and still give you the wrong person. This is the central problem in identity enrichment: a name is not a unique identifier.

The safest workflow separates finding candidates from retrieving a profile. Personpages does this in two API calls so your application, operator, or end user can confirm the intended person before enrichment begins.

Why one-call people search creates bad data

Suppose your input is "Alex Smith, London." Several people may share that name and city. If an API silently picks one result, your database can inherit somebody else's employer, social accounts, salary estimate, or public-record signals.

The error becomes more expensive when that profile flows into a CRM, fraud review, marketplace, or internal research tool. Confidence scores help, but they do not replace disambiguation.

A safer two-step API workflow

1. Send a name and any known age, city, or country to POST /api/public/v1/lookup.
2. Receive a free candidate list with a search ID, candidate IDs, location and employer hints, confidence, evidence, and source URLs.
3. Show those candidates to a user or apply your own matching rules.
4. Send the chosen search ID and candidate ID to the same endpoint.
5. Receive the structured full profile as JSON. Only this second step is counted as a lookup.

The request starts with an authorization header containing your API key and a JSON body such as name: Jane Doe, city: Berlin, country: Germany. The second request contains only the returned search_id and selected candidate_id.

Fields worth using for disambiguation

• Location: city and country usually eliminate the largest group of false matches.
• Employer and role: useful when enriching leads or professional records.
• Age estimate: valuable when two people share a name and location.
• Evidence: lets your application explain why a candidate matched.
• Source URLs: allow manual review for sensitive workflows.
• Confidence: useful for routing low-confidence matches to review, not for blindly accepting them.

When direct mode makes sense

Personpages also supports direct: true, which skips candidate selection and returns the best match. It is useful for low-risk batch enrichment where speed matters more than certainty.

Do not use direct mode merely to save interface work. For user-facing search, compliance review, or any workflow where a wrong identity causes harm, expose the candidate step.

What the profile response contains

The selected-person response includes the profile URL and the structured fields available on the corresponding Personpages profile. These can include identity details, location, employment, estimated compensation, professional history, online footprint, and cited public sources where available.

Public data is uneven. Treat missing fields as unknown, not negative evidence, and retain source links when presenting consequential findings.

Production checklist

• Keep the API key on your server whenever possible.
• Set request timeouts and retry temporary 500 or 502 responses with backoff.
• Never retry a 401 without fixing the key or a 402 without fixing payment.
• Store the returned profile URL and cached status for auditability.
• Let a person review ambiguous candidate lists.
• Do not use Personpages data for FCRA-regulated employment, housing, credit, or insurance decisions.

Start building

Read the complete request and response schemas in the API documentation, or create an API key. Every key includes 50 free lookups per calendar month. After that, new lookups cost $0.39 and cached lookups cost $0.05.