Build Person and Website Enrichment With One REST API

Many research products need two connected views: who is this person? and what is this website or company? Personpages exposes both through authenticated REST endpoints with JSON responses.

The person endpoint is designed around identity disambiguation. The website endpoint turns a domain into a company and trust report. Together they support lead enrichment, marketplace review, editorial research, fraud triage, vendor research, and internal investigation tools.

The two API endpoints

• POST /api/public/v1/lookup searches people by name plus optional age, city, and country. It returns candidates first, then a selected full profile.
• POST /api/public/v1/website accepts a domain and returns the corresponding website report.

Authenticate both with Authorization: Bearer YOUR_API_KEY and send JSON with Content-Type: application/json. Live keys begin with pp_live_ and sandbox keys with pp_test_.

Workflow 1: enrich a person safely

Start with the strongest identity fields your product has. Name alone works, but city, country, age, and known affiliation materially improve matching.

The first response contains candidate IDs and evidence. Your interface can display these choices, or your system can accept a match only when employer and location agree with existing data. Send the chosen IDs in the second call to receive the profile.

This structure is especially useful in CRM tools: a sales representative can choose the correct person rather than silently contaminating the contact record.

Workflow 2: enrich a domain

Send a normalized domain such as example.com to the website endpoint. The report can include company identity, owners and key people, domain registration signals, trust score, reviews, revenue or funding where public, notable news, red flags, and cited sources.

Do not treat a trust score as an automatic verdict. Present the underlying signals so reviewers can distinguish a young legitimate business from a genuinely risky site.

Workflow 3: connect companies and people

A useful research sequence is:

1. Enrich a domain to identify the company and public key people.
2. Pass a key person's name into the person lookup endpoint.
3. Include role and location information in your matching logic.
4. Let the user confirm the correct candidate.
5. Store links between the website report, selected profile, and source URLs.

This produces a navigable company-to-person graph without pretending every name match is certain.

Response handling patterns

• Treat HTTP 400 as an input problem and show a precise validation message.
• Treat HTTP 401 as a missing or invalid API key.
• Treat HTTP 402 as a billing issue that requires a payment-method update.
• Treat HTTP 429 as exhausted free usage without an available payment method.
• Retry temporary 500 or 502 errors with exponential backoff and a maximum attempt count.
• Log the endpoint and cached field, but never log the full API key.

Data model recommendations

Store the Personpages profile or report URL as a stable reference. Keep source URLs alongside extracted claims. Save when your system last requested the data, whether the response was cached, and which input fields produced the match.

Separate facts, estimates, and risk signals in your own interface. Employment and salary fields may be inferred from public signals; missing data does not prove that an event or account does not exist.

Security and acceptable use

API keys should be treated like passwords. Server-side use is safest because it keeps the key away from browser source and client logs. If your architecture calls the API from a browser, restrict exposure and rotate a leaked key immediately from the developer dashboard.

Personpages is not a consumer reporting agency. Do not use the API for FCRA-regulated decisions involving employment, housing, credit, or insurance eligibility.

Build your first integration

Start at the developer page, then copy the tested JavaScript, Python, and curl patterns from the full API reference. The first 50 completed lookups each calendar month are free.