The Dealboard API. Built for humans and AI agents.

Read and write deals, listen for events, and connect Dealboard to AI tools. Use the REST API, signed webhooks, OpenAPI spec, or MCP server depending on what you're building.

Full API reference Get an API key

v1 API note (May 2026 release): the stage field on deal responses is now an object instead of a string. The same applies to from_stage and to_stage on webhook payloads. Update integrations accordingly — see the examples below for the new shape.

# Your first call — list deals
curl "https://app.getdealboard.com/v1/deals" \
  -H "Authorization: Bearer $DEALBOARD_API_KEY"

# Response
{
  "data": [
    {
      "id": "deal_8f3a...",
      "company": "Acme Inc.",
      "amountCents": 4800000,
      "currency": "USD",
      "stage": { "id": "stg_abc123", "name": "Proposal Sent", "region": "anchor", "isAnchor": true },
      "ownerName": "Alex Chen"
    }
  ],
  "next_cursor": null
}

Two objects. One lifecycle.

Dealboard separates raw inbound interest from your sales pipeline, so each gets the right UI and the right schema. They connect via one explicit promote call.

Lead

Raw inbound interest.

Created when someone submits your website form, your hosted contact page, or emails your inbound address. Holds the submitter's contact info, their message, and any enrichment your qualifier writes. Lives in the Leads inbox until you triage it.

Triage states

new contacted promoted junk bad_fit stale

Deal

A real pipeline opportunity.

Has a stage, owner, amount, notes, attached proposals, contracts, and an activity feed. Moves through your board's pipeline regions (early → anchor → late → won/dead). This is what shows up in Reports.

Pipeline regions

early anchor late won dead

Connecting the two. Promote a Lead with POST /v1/leads/{lead_id}/promote. The Lead row sticks around with triage_status: "promoted" and a deal_id pointing at the new Deal — you keep the full inbound provenance forever, and the call is idempotent so replays return the existing deal id without creating a second one.

Move deal data in, keep it current, and send it where your team works.

Dealboard's API covers the workflows that matter most: capturing leads, enriching them, promoting them to deals, updating fields, moving deals through stages, adding notes, and reacting to events.

Read deals

List, filter, search, and paginate deals. Fetch a single deal with its full activity history.

GET /v1/dealsGET /v1/deals/{deal_id}

Create deals

Create deals from forms, lead sources, spreadsheets, internal tools, or another system your team already uses.

POST /v1/deals

Update deals

Change fields, owners, amounts, next steps, and other deal details.

PATCH /v1/deals/{deal_id}

Move deals through stages

Move a deal forward and write the stage change to the activity feed.

POST /v1/deals/{deal_id}/move

List a board's stages

List the customizable stages for a board. Each stage returns its id, name, region, position, and probability.

GET /v1/boards/{board_id}/stages

Add notes

Attach context from calls, meetings, follow-ups, imports, or AI-generated summaries.

POST /v1/deals/{deal_id}/notes

Read leads

List inbound leads from your website form, hosted contact page, or inbound email address. Filter by board or triage status — new, contacted, promoted, junk, bad_fit, stale.

GET /v1/leadsGET /v1/leads/{lead_id}

Create a lead

Push leads into Dealboard server-to-server — e.g. relay your existing website form (Gravity Forms, a webhook, custom code) into the inbox. Authenticated by your API key, so it skips the browser bot-check. Fires the lead.created webhook so a Slack alert and any qualification tool pick it up.

POST /v1/leads

Enrich leads (write qualifier output)

PATCH an enrichment payload onto a lead from your own qualifier — a normalized 0–100 score, a verdict, a markdown writeup, a homepage screenshot, an async status, and a `contact` object for the person you resolved (name, title, email, phone, and a LinkedIn URL). Each PATCH merges the keys you send and appends an audit snapshot. The score + verdict surface as a color badge in the Leads inbox, and when the lead is promoted to a deal the contact you found — your LinkedIn URL included — flows straight onto the deal. Use this from Claude, GPT, Clearbit, Apollo, Hazel, or an internal model.

PATCH /v1/leads/{lead_id}

Triage leads

Flip a lead's lifecycle state — mark contacted after a reply, mark junk for spam, mark bad_fit when it's not your customer. Keeps the inbox clean and feeds the archive view.

PATCH /v1/leads/{lead_id}

Promote a lead to a deal (temporarily disabled)

Currently disabled — this call returns 403 (promote_disabled). Enrich leads via the API; a teammate promotes them to deals from the Dealboard inbox. When re-enabled: turns an inbound lead into a real pipeline opportunity, creating a deal in the same board linked back to the lead row for full provenance. Idempotent — replays return the existing deal id, never a second one.

POST /v1/leads/{lead_id}/promote

List email templates

Fetch your workspace's email templates (most-used first) with subject and body, and log a use when one is sent — keeping the most-used ordering honest. Powers the in-app reply picker and the Dealboard for Gmail extension's compose templates.

GET /v1/templatesPOST /v1/templates/{id}/use

Match a contact to deals & leads

Given an email address, find the deals and leads it belongs to — exact match with a company-domain fallback. Powers the Gmail extension sidebar; each result links straight to the deal or lead.

GET /v1/match

Embed Dealboard in Gmail

Mint a short-lived token that the Dealboard for Gmail extension redeems to show the matched deal or lead — the real, editable Dealboard view — inside Gmail's sidebar. The embedded session is partitioned to Gmail and re-checks workspace membership.

POST /v1/embed-token

React to events

Subscribe to pipeline and lead events with HMAC-signed webhooks (or point a Slack/Teams/Discord webhook at them). lead.created fires the moment a lead lands — wire it to a Slack alert or a qualification bot.

deal.createddeal.stage_changeddeal.wonlead.created

From zero to first call in minutes.

Create a key. Make your first request. Move a deal.

Step 01

Create a key.

Sign in at app.getdealboard.com, then open Settings → API Keys and click Create key. The full key is shown once — copy it immediately. Name it for what it powers so you can revoke just that one later. Free workspaces get 2 keys; paid plans are unlimited.

Step 02

Make your first call.

Hit GET /v1/deals to confirm your key works. It returns the deals in your workspace.

Step 03

Create or update a deal.

Post to /v1/deals, add a note, or move a deal to a new stage. Use idempotency keys when retrying create requests.

# Create a deal
curl "https://app.getdealboard.com/v1/deals" \
  -X POST \
  -H "Authorization: Bearer $DEALBOARD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4a92-init-import" \
  -d '{
    "boardId": "board_8f3a...",
    "name": "Acme — Series B platform",
    "company": "Acme Inc.",
    "amountCents": 4800000,
    "stageId": "stg_abc123"
  }'

Qualify an inbound lead with AI

Subscribe to lead.created, score the lead with your own model or tool, and PATCH the result back. Your score + verdict render as a color badge in the inbox; your markdown writeup and the website screenshot show on the lead detail; and the contact you resolved — LinkedIn included — flows onto the deal when the lead is promoted.

# 1. A new lead just landed (via lead.created webhook or GET /v1/leads?view=active).
# 2. Write your qualifier's output back onto it:
curl "https://app.getdealboard.com/v1/leads/lead_7c2f..." \
  -X PATCH \
  -H "Authorization: Bearer $DEALBOARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enrichment": {
      "status": "complete",
      "score": 82,                        # normalized 0–100 (drives badge color + sort)
      "scoreDisplay": "8/10",             # how you show it
      "verdict": "Reach out to learn more",
      "body": "**Strong fit.** Series B telehealth co...\n\n✅ Green flags:\n- 50-state prescribing matches our offering",
      "screenshot": "https://img.example.com/acme-home.png",
      "provider": "your-qualifier",
      "contact": {                          # the person you resolved — gap-fills the deal on promote
        "name": "Dana Smith",
        "title": "VP of Product",
        "email": "dana@acme.io",
        "linkedin": "https://www.linkedin.com/in/dana-smith"
      }
    }
  }'

# 3. When the lead is promoted, the deal inherits the contact —
#    including the LinkedIn URL — automatically.
curl "https://app.getdealboard.com/v1/leads/lead_7c2f.../promote" \
  -X POST -H "Authorization: Bearer $DEALBOARD_API_KEY"

Connect AI agents to your deal data.

Dealboard gives AI tools structured ways to read deals, add notes, move deals, search deal history, and pull dealboard summaries without scraping screens or guessing how the app works.

MCP server

@dealboard/mcp

Use with Claude, Cursor, and any MCP-compatible client.

npx -y --package=@dealboard/mcp dealboard-mcp

Available actions

list_dealsget_dealcreate_dealupdate_dealmove_dealadd_notesearch_dealsget_pipeline_summaryget_weighted_pipelinelist_leadsget_leadcreate_leadpatch_lead_enrichmenttriage_leadpromote_lead

Remote /mcp only — interactive cards

OAuth-authenticated tools that render Dealboard report cards inline in MCP Apps hosts (ChatGPT, Claude) — and return the underlying numbers so the assistant can answer follow-up questions.

show_dealboard_summaryshow_this_monthshow_deals_wonshow_deal_progress

Remote /mcp only — report image export

Return a PNG of the exact app surface (the same image the app's "Save as PNG" exports), ready to post into Slack, email, or decks. One tool, parameterized by report.

export_report_image

OpenAPI 3.1 spec

Use the OpenAPI spec with ChatGPT Actions, code-generation tools, internal agents, or custom workflows.

app.getdealboard.com/openapi.json

Full API reference

Every endpoint, parameter, request/response shape, and error code — rendered interactively from the OpenAPI 3.1 spec.

Browse the API reference

Designed for

Claude DesktopClaude CodeCursorWindsurfChatGPT ActionsOpenAI CodexVS Code MCP extensions

Webhooks that keep your other systems current.

Subscribe to deal changes and Dealboard will send a signed JSON POST to your endpoint. Every payload includes an HMAC signature so your system can verify where it came from.

Events

deal.created
deal.stage_changed
deal.won
lead.created

# Example payload (deal.stage_changed)
{
  "event": "deal.stage_changed",
  "deal_id": "deal_8f3a...",
  "from_stage": { "id": "stg_def456", "name": "In Discussion", "region": "early" },
  "to_stage": { "id": "stg_abc123", "name": "Proposal Sent", "region": "anchor" },
  "changed_by": "alex@example.com",
  "changed_at": "2026-05-20T18:42:00Z"
}

# Headers
X-Dealboard-Signature: sha256=...

Built for secure integrations.

Bearer-token authentication, HTTPS-only API requests, per-key rate limits, workspace-isolated access, one-click key revocation, and encryption at rest for customer data and files.

Customer data and files are encrypted at rest
API keys are hashed before storage
Webhooks include HMAC signatures for verification
API keys can be revoked anytime
Rate limits apply per key
Workspace access is isolated by design

Start building with Dealboard.

Create an API key, run the quickstart, and connect deals, notes, webhooks, and AI agents.

Get an API key Get Started Free