PloidDocs
Person

Person

Get a reviewed person report, structured professional history, source links, and evidence-backed interests.

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_..." },
    "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:

typeResearchPrice
deep (default)The full reviewed research run25 ACU
standardFewer page reads, the same review rules10 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 (https only).
  • anchors — up to 10 unique public https URLs 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, or null when no URL supports it.
  • research.publications[], research.patents[], work.open_source[] and media.appearances[] — reviewed findings in each category, one entry per reviewed claim. Each entry has title, organization (publisher, venue, project owner or show), period, url, statement, evidence_quote, source_urls and timeframe. title, organization and period are null unless the cited evidence states them. The same claims also appear in summary. A category with no reviewed claims is an empty array.
  • age_range — currently null; 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.