---
title: "List leads"
method: GET
path: "/v1/leads"
tags: ["Leads"]
---

# List leads

`GET /v1/leads`

## Request

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

Returns inbound leads from your website forms, hosted contact pages, and
inbound email address. Filter by `boardId` to narrow to one board, and by
`triageStatus` to filter the inbox (e.g. only `new` to mimic the unread tray).

Leads and Deals are separate objects — see the API description for the
lifecycle. Promote a Lead to a Deal via POST /v1/leads/{id}/promote.

## Query parameters

- `limit` integer
- `cursor` string
- `boardId` string, uuid
- `triageStatus` 'new' | 'contacted' | 'promoted' | 'junk' | 'bad_fit' | 'stale'
- `q` string

## Response `200`

OK

- LeadList
  - `data` Lead[], required
    - `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
  - `hasMore` boolean, required
  - `nextCursor` string, nullable, required: Pass as `?cursor=` on the next request to fetch the next page.

## Other responses

- `401`: Missing or invalid API key.
- `429`: Rate limit exceeded.

---

[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)