Person
Get a reviewed person report, structured professional history, source links, and evidence-backed interests.
Get a person
POST /v1/personRequires people:enrich. Identify the person with exactly one of person_id,
linkedin_url, or name plus company_domain.
{
"identifier": { "person_id": "person_..." },
"type": "deep",
"include": ["work_email", "phone"]
}The request is strict. include is optional and accepts one to three unique
values from work_email, personal_email, and phone. Requested contacts are
returned on the person record in data.contact; missing and unavailable fields
include a status rather than changing the profile result.
Research level
type is optional and sets how much research runs:
type | Research | Price |
|---|---|---|
deep (default) | The full reviewed research run | 25 ACU |
standard | Fewer page reads, the same review rules | 10 ACU |
A stored deep profile also answers a standard request, but a stored standard
profile never answers a deep request; that queues new research. The access
receipt records the level paid for. A deep receipt covers later standard
reads for free. A standard receipt asked for deep is charged only the 15 ACU
difference, and its 90-day window restarts from the upgrade. meta.usage.billed
names the level charged: person.standard or person.deep.
What you already know
Three optional fields let you tell research what you know and what you want:
goal— up to 2,000 characters describing what to look for, for example"What has she said about hiring on podcasts?". Research gives it priority.website_url— the person's own site (httpsonly).anchors— up to 10 unique publichttpsURLs you know belong to this person, such as their X profile, YouTube channel or a podcast episode they were on. Research reads them first and treats anything connected to them as the same person.
Anchors are taken as your statement; a wrong anchor gives a profile of the wrong person. A request with any of these fields always runs new research and is never served from, or saved to, the shared stored profile. It is billed like any other request, under the same 90-day access receipt.
An eligible reviewed snapshot returns 200. A first access can be billed even
when its snapshot is already cached. Eligible stale snapshots return with
meta.stale: true while a background refresh is queued. A cache miss or a snapshot
that predates the required review returns a durable 202 run:
{
"data": {
"run_id": "...",
"status": "queued",
"poll_url": "/v1/person/runs/..."
},
"meta": {
"request_id": "...",
"usage": { "acu_used": 0, "billed": [], "free": [], "not_found": [] }
}
}Poll GET /v1/person/runs/{id} for the normal person response, or cancel an
active run with DELETE /v1/person/runs/{id}. Run inputs and results are
retrievable for seven days, then polling returns 410 run_expired.
The queued response is not the finished research. Fresh research requires the shared Eve service and can take minutes; keep the run ID and poll rather than holding a single HTTP request open. Local examples completed in about 100–130 seconds, but these are individual observations, not a latency guarantee. The deep research call has a 15-minute deadline; queue waiting and retries can add time. Cached results do not repeat research. Disconnecting a client does not cancel its background run.
What comes back
Every found record leads with:
summary— the reviewed research report, including source-supported claims, time labels, coverage, and limitations. It is not guaranteed to be a short biography.source_links— up to 25 deduplicated public evidence links, ordered by verification status and confidence.presence.platforms[]— public accounts whose identity links passed review. Each account preserves its evidence statement and supporting source URLs. Profile details, audience counts and public activity are populated only when the cited evidence supports them; unavailable values remain null or empty.signals.interests[].source_url— the direct evidence URL for an interest, ornullwhen no URL supports it.research.publications[],research.patents[],work.open_source[]andmedia.appearances[]— reviewed findings in each category, one entry per reviewed claim. Each entry hastitle,organization(publisher, venue, project owner or show),period,url,statement,evidence_quote,source_urlsandtimeframe.title,organizationandperiodarenullunless the cited evidence states them. The same claims also appear insummary. A category with no reviewed claims is an empty array.age_range— currentlynull; age is not inferred from school attendance or old profile descriptions.
The record also contains person_id, identity, the professional, presence and signals sections, and
provenance. Provenance is keyed by response field path and records source,
source_url, first_seen, last_seen, and confidence; unknown fields do not
receive invented provenance.
The shared workflow reviews the identity, quotations, meaning, and temporal context of claims before publishing them. Search snippets are discovery leads, not supporting evidence. Source review does not independently establish that every source is true, and reading a page today does not make its claims current.
professional.history[] and professional.education[] retain reviewed
timeframe and evidence_statement fields. professional.current and the
corresponding identity headline/company/location fields require an explicit
source-dated current-status claim within 90 days when returned. Undated, stale,
future-dated or conflicting current values remain null. Historical claims remain
available in the summary and history. Skills and social details likewise require
reviewed evidence. Confidence values are compatibility scores, not calibrated
probabilities.
Uncertain identity
A completed run can return 200 with data: null and meta.resolution: "unsure"
when discovery cannot establish one person's identity:
{
"data": null,
"meta": {
"request_id": "...",
"found": false,
"stale": false,
"resolution": "unsure",
"reason": "ambiguous_identity",
"message": "The available evidence does not reliably distinguish between matching people.",
"limitations": [],
"suggested_clues": ["linkedin_url", "personal_website"],
"usage": { "acu_used": 0, "billed": [], "free": [], "not_found": [] }
}
}The reason is ambiguous_identity or insufficient_evidence. This does not mean
the person does not exist; no profile or negative-cache record is created and no
successful-profile charge is applied. Provider outages, failed review, and
invalid results remain operational errors rather than uncertainty.
Use a supported identifier, such as linkedin_url, when retrying, and add
website_url or anchors if you know the person's own site or accounts. The
current response does not return selectable candidate people or resume from a
candidate choice.
Usage
The first successful profile costs 25 ACU ($2.50 face value) for deep
and 10 ACU for standard, on every plan. The same organization can reread
that person at the same or a lower level free for 90 days; stale evidence is refreshed inside that window without another
charge. Contacts are billed on every request that includes them, only when
found: 1 credit for work_email, 3 for personal_email, and 10 for phone.
These are the same per-field prices as /v1/enrich.
Every response includes usage with acu_used, billed, free, and not_found.
For successful responses it is meta.usage; for errors it is error.usage.
Active-window rereads, validation errors, failures, uncertain outcomes, and
not-found results use 0 ACU.
