contacts

Read or run Dex Research on a contact (v2)

Dex Research: a cited web research note about one contact (who they are, current focus, background, interests) plus structured findings (LinkedIn, website, email, phone) with per-finding confidence and evidence. The default body ({}) only READS the stored research and never generates — research is null when nothing has been researched yet — and reports where the contact's current or latest run is (in_progress, stage, run_id, failure). { run: true } starts the pipeline (web search + page extraction + LLM summary); a run whose stored result is under 30 days old returns the cached note at once unless force: true. Otherwise the run executes in the background and the call answers immediately with in_progress: true and the run's run_id — poll the default body every few seconds until in_progress is false: the run finished when research.run_id equals that run_id, and failed when failure is set (unavailable: a research provider is down, retry later). Runs usually take 20–60 seconds and occasionally over two minutes. in_progress: true on a run request can also mean another request's run is already in flight — poll it the same way instead of starting another. A run auto-fills the contact's EMPTY linkedin / website fields when a high-confidence finding exists (those findings come back auto_applied); email and phone findings stay pending for the user to apply. A run request that would start a paid run is refused with 429 research_limit_reached once the user has used up a fair-use window — 100 runs per UTC calendar month and 50 per UTC day, counting forced re-runs and runs that later fail but never cache hits or a run already in flight — with error.details { window: "month" | "day", limit, resets_at } and Retry-After set to the seconds until resets_at. Unlike the per-minute rate_limited 429 it will not clear on a retry: do not retry before resets_at. The default-body read is never limited this way. 404 when the contact does not belong to the authenticated user.

post/v2/contacts/{contactId}/research

Path parameters

contactIdstring uuid required

Headers

Idempotency-Keystring
Example:01HV8N6X7K3P9Q5R2T4Y6W8Z0A

Optional. Accepted to dedupe retries on this endpoint. See apps/rest-api/src/shared/idempotency.ts.

Request body

runboolean
forceboolean

Response

Successful response

Changes

Changed in 2 of the 37 revisions of this API.4

    • ○

      added the required property / to the response with the status

      response-required-property-added

    • ○

      added the required property / to the response with the status

      response-required-property-added

    • ○

      added the required property / to the response with the status

      response-required-property-added

    • ○

      endpoint added

      endpoint-added