---
title: "Update triage status and/or enrichment"
method: PATCH
path: "/v1/leads/{id}"
tags: ["Leads"]
---

# Update triage status and/or enrichment

`PATCH /v1/leads/{id}`

## Request

- Base URL: `https://app.getdealboard.com`
- URL: `https://app.getdealboard.com/v1/leads/{id}`
- Auth: HTTP bearer

Two independent updates can ride in the same call:

- `triageStatus` — flip lifecycle state (`new` → `contacted`, `junk`,
  `bad_fit`, or `stale`). Setting `contacted` stamps `contactedAt`;
  setting `junk` stamps `junkedAt` + the calling user. **`promoted` is NOT
  settable here** — call `POST /v1/leads/{id}/promote` instead, which
  creates the Deal and links it.

- `enrichment` — merge a free-form enrichment payload from your qualifier.
  Top-level keys you send overwrite existing keys; keys you omit are
  preserved. Each PATCH appends a snapshot to `enrichment.history` (which
  you cannot overwrite — it's server-managed audit). Use this to push AI
  scoring, summaries, or attachment URLs onto a Lead.

Empty body is allowed — returns the Lead unchanged.

## Headers

- `Idempotency-Key` string

## Request body

- object: All fields are optional; only the ones you send are applied.
  - `triageStatus` 'new' | 'contacted' | 'junk' | 'bad_fit' | 'stale': `promoted` is intentionally excluded — promoting a Lead requires creating a Deal, which is the dedicated `POST /v1/leads/{id}/promote` endpoint.
  - `enrichment` LeadEnrichment: Free-form qualifier payload. Common fields shown below — additional keys are preserved verbatim. `history` is server-managed; PATCH bodies cannot overwrite it.
    - `status` 'queued' | 'in_progress' | 'complete' | 'skipped': Async lifecycle. Send `in_progress` when your tool claims the lead (scoring can take minutes); the inbox shows "Scoring…". Then `complete` (or `skipped`) with the result.
    - `score` number: Normalized 0–100 fit/ICP score. Drives the inbox badge color + sort. Send the human-readable original (e.g. "9/10") in `scoreDisplay`.
    - `scoreDisplay` string: Human-readable score as your tool renders it, e.g. "9/10" or "B+". Display-only.
    - `verdict` string: Short free-form recommendation/label, e.g. "Reach out and chat", "Ignore". Shown next to the score.
    - `body` string: Rich writeup (markdown — bold/bullets/emoji), shown on the lead detail.
    - `provider` string: Which tool produced this (e.g. "hazel", "clearbit").
    - `contact` object: Enriched CONTACT — the person behind the lead. Generic across every qualifier (mirrors a deal’s own contact fields). When the lead is promoted to a deal, these GAP-FILL the deal’s primary contact (the lead’s own values win). Recommended to populate — especially `linkedin`, which lands in the deal’s LinkedIn field just like phone/email/title.
      - `name` string: Full name of the contact.
      - `title` string: Job title, e.g. "VP of Product".
      - `email` string, email
      - `phone` string
      - `linkedin` string, uri: Full https URL to the contact’s LinkedIn profile, e.g. "https://www.linkedin.com/in/jane-doe". Strongly recommended — it populates the promoted deal’s LinkedIn field. (If omitted, Dealboard also picks up the first linkedin.com/in/ URL it finds in `body`.)
      - `website` string, uri
    - `screenshot` string: A website/homepage screenshot for the enrichment card. PATCH a public https URL; Dealboard downloads the image and stores it permanently, so it survives even if your original URL later expires. On read, this is a durable Dealboard-hosted URL.
    - `screenshotSource` string, uri: Read-only. The original provider URL the stored `screenshot` was ingested from.
    - `summary` string
    - `notes` string
    - `attachments` object[]
      - `url` string, required: Image URL. PATCH a public https URL; image attachments are downloaded and stored permanently (on read, `url` is a durable Dealboard-hosted URL).
      - `filename` string
      - `kind` string
      - `sourceUrl` string, uri: Read-only. The original provider URL this stored image was ingested from.
    - `history` LeadEnrichmentHistoryEntry[]: Append-only audit trail of every PATCH /v1/leads/{id} call. Server-managed.
      - `at` string, date-time, required
      - `by` string, required: API key id that wrote the enrichment patch.
      - `payload` object, required: The keys that were merged at this point in time.

## Response `200`

OK

- Lead
  - `id` string, uuid, required
  - `boardId` string, uuid, required
  - `triageStatus` 'new' | 'contacted' | 'promoted' | 'junk' | 'bad_fit' | 'stale', required: Lifecycle marker for the Lead inbox. `new` → `contacted` is recorded when a reply goes out; `promoted`/`junk`/`bad_fit` are terminal triage outcomes; `stale` is set by a daily cron if a Lead sits in `new` too long.
  - `source` 'form' | 'email', required: How the Lead arrived: `form` (website/hosted form) or `email` (inbound email).
  - `dealId` string, uuid, nullable, required: Set once the Lead has been promoted to a Deal via POST /v1/leads/{id}/promote. Null otherwise.
  - `contact` object, required: Submitted form values verbatim. Same shape as the form fields the workspace admin configured.
    - `firstName` string, nullable, required
    - `lastName` string, nullable, required
    - `email` string, email, nullable, required
    - `phone` string, nullable, required
    - `companyName` string, nullable, required
    - `companyWebsite` string, nullable, required
    - `message` string, nullable, required
    - `howHeard` string, nullable: "How did you hear about us?" answer, when collected.
    - `consent` boolean, nullable: Marketing/SMS consent given on the form (null = not asked).
  - `enrichment` LeadEnrichment, required: Free-form qualifier payload. Common fields shown below — additional keys are preserved verbatim. `history` is server-managed; PATCH bodies cannot overwrite it.
    - `status` 'queued' | 'in_progress' | 'complete' | 'skipped': Async lifecycle. Send `in_progress` when your tool claims the lead (scoring can take minutes); the inbox shows "Scoring…". Then `complete` (or `skipped`) with the result.
    - `score` number: Normalized 0–100 fit/ICP score. Drives the inbox badge color + sort. Send the human-readable original (e.g. "9/10") in `scoreDisplay`.
    - `scoreDisplay` string: Human-readable score as your tool renders it, e.g. "9/10" or "B+". Display-only.
    - `verdict` string: Short free-form recommendation/label, e.g. "Reach out and chat", "Ignore". Shown next to the score.
    - `body` string: Rich writeup (markdown — bold/bullets/emoji), shown on the lead detail.
    - `provider` string: Which tool produced this (e.g. "hazel", "clearbit").
    - `contact` object: Enriched CONTACT — the person behind the lead. Generic across every qualifier (mirrors a deal’s own contact fields). When the lead is promoted to a deal, these GAP-FILL the deal’s primary contact (the lead’s own values win). Recommended to populate — especially `linkedin`, which lands in the deal’s LinkedIn field just like phone/email/title.
      - `name` string: Full name of the contact.
      - `title` string: Job title, e.g. "VP of Product".
      - `email` string, email
      - `phone` string
      - `linkedin` string, uri: Full https URL to the contact’s LinkedIn profile, e.g. "https://www.linkedin.com/in/jane-doe". Strongly recommended — it populates the promoted deal’s LinkedIn field. (If omitted, Dealboard also picks up the first linkedin.com/in/ URL it finds in `body`.)
      - `website` string, uri
    - `screenshot` string: A website/homepage screenshot for the enrichment card. PATCH a public https URL; Dealboard downloads the image and stores it permanently, so it survives even if your original URL later expires. On read, this is a durable Dealboard-hosted URL.
    - `screenshotSource` string, uri: Read-only. The original provider URL the stored `screenshot` was ingested from.
    - `summary` string
    - `notes` string
    - `attachments` object[]
      - `url` string, required: Image URL. PATCH a public https URL; image attachments are downloaded and stored permanently (on read, `url` is a durable Dealboard-hosted URL).
      - `filename` string
      - `kind` string
      - `sourceUrl` string, uri: Read-only. The original provider URL this stored image was ingested from.
    - `history` LeadEnrichmentHistoryEntry[]: Append-only audit trail of every PATCH /v1/leads/{id} call. Server-managed.
      - `at` string, date-time, required
      - `by` string, required: API key id that wrote the enrichment patch.
      - `payload` object, required: The keys that were merged at this point in time.
  - `createdAt` string, date-time, required
  - `contactedAt` string, date-time, nullable, required
  - `promotedAt` string, date-time, nullable, required
  - `junkedAt` string, date-time, nullable, required

## Other responses

- `400`: Invalid input (e.g. attempted PATCH to triageStatus="promoted").
- `404`: Lead not found in your workspace.

---

[API](https://skmtc.dev/getdealboard/apis/dealboard-api.md) · [All operations](https://skmtc.dev/getdealboard/apis/dealboard-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getdealboard/apis/dealboard-api/revisions/4066bf9d265e?raw)