Person

Get a person

POST /v1/person

Requires people:enrich. Identify the person with exactly one of person_id, linkedin_url, or name plus company_domain.

{
    "identifier": { "person_id": "person_..." }
}

The request is strict. Removed depth and include fields return 422 rather than silently changing price or output.

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, or null when no URL supports it.
• age_range — currently null; age is not inferred from school attendance or old profile descriptions.

The record also contains person_id, identity, all three deep 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. A personal website is a clue a conversational caller can request; website_url is not an accepted field in this endpoint's strict request schema. The current response does not return selectable candidate people or resume from a candidate choice.

Usage

/v1/person has one mode: deep. The first successful profile costs 25 ACU ($2.50 face value) on every plan. The same organization can reread that person free for 90 days; stale evidence is refreshed inside that window without another charge.

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.