Dealboard / API Reference

Dealboard API Reference

The Dealboard REST API lets you read and update your sales pipeline programmatically — list, create, and move deals, manage inbound leads, read weighted-pipeline reports, and subscribe to webhooks. It is the same API behind the ChatGPT and Claude connectors and the @dealboard/mcp server. The full machine-readable spec is published as OpenAPI 3.1.

Base URL & versioning

All endpoints are served under https://app.getdealboard.com/v1. Responses are JSON. Collections are cursor-paginated (limit + cursor) and ordered newest-first. Write endpoints accept an Idempotency-Key header.

Authentication

Authenticate with a bearer token — either a workspace API key (prefix dlb_live_, created in Settings → API Keys) or an OAuth 2.1 access token (used by the AI connectors). Send it as Authorization: Bearer <token>. Verify a credential and read its scopes with GET /v1/me. Rate limits: 600 requests/min per key, 2000/min per workspace.

Endpoints

Deals

  • GET /v1/deals — list deals (filters: board, stage, status)
  • POST /v1/deals — create a deal
  • GET /v1/deals/{id} — fetch one deal
  • PATCH /v1/deals/{id} — update deal fields
  • DELETE /v1/deals/{id} — soft-delete a deal
  • POST /v1/deals/{id}/move — move a deal to a stage (stamps won/dead, fires webhooks)
  • GET / POST /v1/deals/{id}/notes — list / add notes
  • GET /v1/deals/{id}/activity — full activity feed

Leads & qualification

  • GET /v1/leads — list inbound leads (filter by triage status)
  • GET /v1/leads/{id} — fetch one lead, including any enrichment written to it
  • POST /v1/leads — create a lead server-to-server (relay your website form or another source). Fires lead.created.
  • PATCH /v1/leads/{id} — triage, or write enrichment: status, score (normalized 0–100), scoreDisplay, verdict, body (markdown), screenshot (URL), and a generic contact object — name, title, email, phone, linkedin. Each PATCH merges + appends an audit snapshot.
  • POST /v1/leads/{id}/promote — promote a lead to a deal (idempotent). Gap-fills the new deal's contact from the enrichment — the LinkedIn URL lands on the deal alongside title/email/phone.

Boards & stages

  • GET /v1/boards — list boards
  • POST /v1/boards — create a board
  • GET /v1/boards/{id} — fetch one board
  • PATCH /v1/boards/{id} — update a board
  • GET /v1/boards/{id}/stages — list a board's stages

Pipeline reports

  • GET /v1/reports/weighted-pipeline — probability-weighted pipeline totals + per-stage breakdown

Webhooks

  • GET /v1/webhooks — list webhook subscriptions
  • POST /v1/webhooks — subscribe (events: deal.created, deal.stage_changed, deal.won, lead.created) with HMAC signing
  • DELETE /v1/webhooks/{id} — unsubscribe

Notes & identity

  • PATCH / DELETE /v1/notes/{id} — edit / delete a note
  • GET /v1/me — current user, workspace, and granted scopes

Loading the interactive reference… If it doesn't appear, view the raw OpenAPI spec or head back to the developers overview.