Dealboard Leads API

The Leads API from Dealboard — 3 operation(s) for leads.

GitHub OpenAPI

Operations 5

GET /v1/leads List leads #
POST /v1/leads Create a lead #
GET /v1/leads/{id} Get one lead #
PATCH /v1/leads/{id} Update triage status and/or enrichment #
POST /v1/leads/{id}/promote Promote a Lead to a Deal (temporarily disabled) #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/dealboard:dealboard-leads-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

dealboard-leads-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Dealboard Leads API
  version: 1.2.0
  contact:
    name: Dealboard
    email: support@getdealboard.com
    url: https://getdealboard.com/developers
  description: 'Operations tagged Leads across 2 of this provider''s published API definitions: openapi.json, dealboard-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.getdealboard.com
  description: Production
security:
- BearerApiKey: []
tags:
- name: Leads
paths:
  /v1/leads:
    get:
      summary: List leads
      description: '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.'
      tags:
      - Leads
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        description: Max number of items per page (1-100).
      - name: cursor
        in: query
        schema:
          type: string
        description: Opaque cursor from a previous response's `nextCursor`.
      - name: boardId
        in: query
        schema:
          type: string
          format: uuid
        description: Filter to leads on this board.
      - name: triageStatus
        in: query
        schema:
          type: string
          enum:
          - new
          - contacted
          - promoted
          - junk
          - bad_fit
          - stale
        description: Filter to one triage status. Unknown values return an empty list (forward-compatible — clients can pre-filter without coupling to the enum).
      - name: q
        in: query
        schema:
          type: string
          maxLength: 120
        description: Case-insensitive substring search over company name, company website, work email, first name and last name. The lookup to use for "has this company ever contacted us?" — it searches the whole workspace server-side, so an empty result means no match.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadList'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: getV1Leads
      x-operation-id-source: derived
    post:
      operationId: createLead
      summary: Create a lead
      description: 'Create a lead via the API — the server-to-server intake used by a website-form relay (e.g. a WordPress/Gravity Forms feed). Unlike the public browser form endpoint, this is authenticated by your API key, so submissions are trusted (not bot-checked). Fires the `lead.created` webhook so a Slack alert and any lead-qualification tool can pick it up. Lands on the workspace''s first board unless `boardId` is given. Scope: leads:write.'
      tags:
      - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: At least one of workEmail, firstName, lastName, companyName, or message is required.
              properties:
                boardId:
                  type: string
                  format: uuid
                  description: Destination board. Defaults to the workspace's first board.
                firstName:
                  type: string
                lastName:
                  type: string
                workEmail:
                  type: string
                  format: email
                phone:
                  type: string
                companyName:
                  type: string
                companyWebsite:
                  type: string
                message:
                  type: string
                howHeard:
                  type: string
                consent:
                  type: boolean
                  description: Accepts a real boolean or a string ("true"/"1"/"yes") — a server-to-server form relay sends strings.
                consentText:
                  type: string
                source:
                  type: string
                  enum:
                  - form
                  - email
                  - import
                sourceUrl:
                  type: string
                  description: Page the form was submitted from (website-form relay).
                pageTitle:
                  type: string
                  description: Title of the page the form was on.
                referrer:
                  type: string
                  description: document.referrer at submission, if known.
                utmSource:
                  type: string
                utmMedium:
                  type: string
                utmCampaign:
                  type: string
                utmTerm:
                  type: string
                utmContent:
                  type: string
                gclid:
                  type: string
                fbclid:
                  type: string
                msclkid:
                  type: string
            example:
              firstName: AJ
              workEmail: aj@arcs.health
              companyWebsite: covenant.clinic
              message: Exploring telehealth infrastructure.
              howHeard: Online
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '400':
          description: Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Board not found in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    servers:
    - url: https://app.getdealboard.com
      description: Production
  /v1/leads/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      summary: Get one lead
      tags:
      - Leads
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '404':
          description: Lead not found in your workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: getV1LeadsById
      x-operation-id-source: derived
    patch:
      summary: Update triage status and/or enrichment
      description: '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.'
      tags:
      - Leads
      parameters:
      - name: Idempotency-Key
        in: header
        schema:
          type: string
        description: Optional client-chosen string. If the same key is sent twice within 24h with the same body, the original response is replayed.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: All fields are optional; only the ones you send are applied.
              properties:
                triageStatus:
                  type: string
                  enum:
                  - new
                  - contacted
                  - junk
                  - bad_fit
                  - stale
                  description: '`promoted` is intentionally excluded — promoting a Lead requires creating a Deal, which is the dedicated `POST /v1/leads/{id}/promote` endpoint.'
                enrichment:
                  $ref: '#/components/schemas/LeadEnrichment'
                  description: Merged into existing enrichment. Keys you send overwrite; keys you omit are preserved. `history` cannot be overwritten.
            examples:
              flipToContacted:
                summary: Mark as contacted
                value:
                  triageStatus: contacted
              pushScore:
                summary: Push an AI score + summary
                value:
                  enrichment:
                    score: 0.82
                    summary: High intent. Mentions budget, decision-maker, timeline.
                    notes: Asked about pricing. Looks like 20-50 user range.
              bothInOneCall:
                summary: Score + transition in one call
                value:
                  triageStatus: contacted
                  enrichment:
                    score: 0.82
                    summary: High intent.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '400':
          description: Invalid input (e.g. attempted PATCH to triageStatus="promoted").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Lead not found in your workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: patchV1LeadsById
      x-operation-id-source: derived
    servers:
    - url: https://app.getdealboard.com
      description: Production
  /v1/leads/{id}/promote:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      summary: Promote a Lead to a Deal (temporarily disabled)
      description: '⚠️ **Temporarily disabled.** This endpoint currently returns `403`

        (`code: "promote_disabled"`). Enrich leads via `PATCH /v1/leads/{id}`; a

        teammate promotes them to deals from the Dealboard inbox. The behavior

        below applies when promotion is re-enabled.


        Creates a new Deal in the same board''s pipeline using the Lead''s submitter

        as the primary contact and the form fields as the Deal name + company. The

        Lead row is updated with `triageStatus="promoted"` and `dealId` pointing at

        the new Deal — provenance is preserved.


        Idempotent on `leadId`: replays return the existing Deal id without

        creating a second one.'
      tags:
      - Leads
      parameters:
      - name: Idempotency-Key
        in: header
        schema:
          type: string
        description: Optional client-chosen string. If the same key is sent twice within 24h with the same body, the original response is replayed.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: All fields optional. Defaults come from the Lead form + the board's configured defaults.
              properties:
                dealName:
                  type: string
                  maxLength: 200
                  description: 'Override the Deal name. Default: companyName, or full name, or workEmail, or "New deal".'
                ownerUserId:
                  type: string
                  format: uuid
                  description: 'Override the Deal owner. Default: the lead form''s configured default owner.'
      responses:
        '200':
          description: OK — the Lead was already promoted. Returns the existing Deal id.
          content:
            application/json:
              schema:
                type: object
                required:
                - dealId
                - leadId
                properties:
                  dealId:
                    type: string
                    format: uuid
                  leadId:
                    type: string
                    format: uuid
        '201':
          description: Created — the Lead was promoted; the Deal is new.
          content:
            application/json:
              schema:
                type: object
                required:
                - dealId
                - leadId
                properties:
                  dealId:
                    type: string
                    format: uuid
                  leadId:
                    type: string
                    format: uuid
        '400':
          description: Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Lead not found in your workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Board has no stages — add stages before promoting leads.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: postV1LeadsByIdPromote
      x-operation-id-source: derived
    servers:
    - url: https://app.getdealboard.com
      description: Production
components:
  schemas:
    Lead:
      type: object
      required:
      - id
      - boardId
      - triageStatus
      - source
      - dealId
      - contact
      - enrichment
      - createdAt
      - contactedAt
      - promotedAt
      - junkedAt
      properties:
        id:
          type: string
          format: uuid
        boardId:
          type: string
          format: uuid
        triageStatus:
          type: string
          enum:
          - new
          - contacted
          - promoted
          - junk
          - bad_fit
          - stale
          description: 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:
          type: string
          enum:
          - form
          - email
          description: 'How the Lead arrived: `form` (website/hosted form) or `email` (inbound email).'
        dealId:
          type:
          - string
          - 'null'
          format: uuid
          description: Set once the Lead has been promoted to a Deal via POST /v1/leads/{id}/promote. Null otherwise.
        contact:
          type: object
          required:
          - firstName
          - lastName
          - email
          - phone
          - companyName
          - companyWebsite
          - message
          description: Submitted form values verbatim. Same shape as the form fields the workspace admin configured.
          properties:
            firstName:
              type:
              - string
              - 'null'
            lastName:
              type:
              - string
              - 'null'
            email:
              type:
              - string
              - 'null'
              format: email
            phone:
              type:
              - string
              - 'null'
            companyName:
              type:
              - string
              - 'null'
            companyWebsite:
              type:
              - string
              - 'null'
            message:
              type:
              - string
              - 'null'
            howHeard:
              type:
              - string
              - 'null'
              description: '"How did you hear about us?" answer, when collected.'
            consent:
              type:
              - boolean
              - 'null'
              description: Marketing/SMS consent given on the form (null = not asked).
        enrichment:
          $ref: '#/components/schemas/LeadEnrichment'
        createdAt:
          type: string
          format: date-time
        contactedAt:
          type:
          - string
          - 'null'
          format: date-time
        promotedAt:
          type:
          - string
          - 'null'
          format: date-time
        junkedAt:
          type:
          - string
          - 'null'
          format: date-time
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          - request_id
          properties:
            type:
              type: string
              description: Coarse machine-readable category.
              enum:
              - authentication_error
              - permission_error
              - invalid_request_error
              - not_found
              - rate_limit_error
              - conflict_error
              - unsupported_media_type
              - method_not_allowed
              - api_error
            code:
              type: string
              description: Finer-grained error code.
            message:
              type: string
              description: Human-readable English explanation.
            request_id:
              type: string
              description: The Dealboard-Request-Id assigned to this request. Quote this when filing a bug.
    LeadEnrichmentHistoryEntry:
      type: object
      required:
      - at
      - by
      - payload
      properties:
        at:
          type: string
          format: date-time
        by:
          type: string
          description: API key id that wrote the enrichment patch.
        payload:
          type: object
          additionalProperties: true
          description: The keys that were merged at this point in time.
    LeadEnrichment:
      type: object
      additionalProperties: true
      description: Free-form qualifier payload. Common fields shown below — additional keys are preserved verbatim. `history` is server-managed; PATCH bodies cannot overwrite it.
      properties:
        status:
          type: string
          enum:
          - queued
          - in_progress
          - complete
          - skipped
          description: 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:
          type: number
          minimum: 0
          maximum: 100
          description: Normalized 0–100 fit/ICP score. Drives the inbox badge color + sort. Send the human-readable original (e.g. "9/10") in `scoreDisplay`.
        scoreDisplay:
          type: string
          description: Human-readable score as your tool renders it, e.g. "9/10" or "B+". Display-only.
        verdict:
          type: string
          description: Short free-form recommendation/label, e.g. "Reach out and chat", "Ignore". Shown next to the score.
        body:
          type: string
          description: Rich writeup (markdown — bold/bullets/emoji), shown on the lead detail.
        provider:
          type: string
          description: Which tool produced this (e.g. "hazel", "clearbit").
        contact:
          type: object
          additionalProperties: false
          description: 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.
          properties:
            name:
              type: string
              description: Full name of the contact.
            title:
              type: string
              description: Job title, e.g. "VP of Product".
            email:
              type: string
              format: email
            phone:
              type: string
            linkedin:
              type: string
              format: uri
              description: 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:
              type: string
              format: uri
        screenshot:
          type: string
          description: 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:
          type: string
          format: uri
          description: Read-only. The original provider URL the stored `screenshot` was ingested from.
        summary:
          type: string
        notes:
          type: string
        attachments:
          type: array
          items:
            type: object
            required:
            - url
            properties:
              url:
                type: string
                description: Image URL. PATCH a public https URL; image attachments are downloaded and stored permanently (on read, `url` is a durable Dealboard-hosted URL).
              filename:
                type: string
              kind:
                type: string
              sourceUrl:
                type: string
                format: uri
                description: Read-only. The original provider URL this stored image was ingested from.
        history:
          type: array
          items:
            $ref: '#/components/schemas/LeadEnrichmentHistoryEntry'
          description: Append-only audit trail of every PATCH /v1/leads/{id} call. Server-managed.
    LeadList:
      type: object
      required:
      - data
      - hasMore
      - nextCursor
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Lead'
        hasMore:
          type: boolean
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass as `?cursor=` on the next request to fetch the next page.
  securitySchemes:
    BearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: dlb_live_<43-char-base62>
      description: API keys are workspace-scoped and inherit the creator's role. Generate in Workspace Settings → API Keys.
    BearerOAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.1 access token (audience-bound to the /mcp resource). Obtained via the authorization-code + PKCE flow — discovery at /.well-known/oauth-authorization-server. Used by the remote MCP endpoint (/mcp) and accepted on /v1/* as well; effective permission is the granted scopes intersected with the user's workspace role.
x-refined-from:
- openapi.json
- dealboard-openapi.json
x-provenance:
  method: harvested
  publisher: Dealboard
  source: https://app.getdealboard.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)