---
title: "Create a deal"
method: POST
path: "/v1/deals"
tags: ["Deals"]
---

# Create a deal

`POST /v1/deals`

## Request

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

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `boardId` string, uuid, required
  - `name` string, required
  - `company` string, nullable
  - `amountCents` integer, nullable
  - `stageId` string: Stage id from the target board. If omitted, defaults to the earliest open stage (region=early, lowest position).
  - `ownerId` string, uuid: Defaults to the API key's creator.
  - `labels` string[]
  - `primaryContactName` string, nullable
  - `primaryContactTitle` string, nullable
  - `primaryContactEmail` string, nullable
  - `primaryContactPhone` string, nullable
  - `primaryContactLinkedin` string, nullable
  - `keyTerms` string, nullable

## Response `201`

Created

- Deal
  - `id` string, uuid, required
  - `boardId` string, uuid, required
  - `name` string, required
  - `company` string, nullable, required
  - `amountCents` integer, nullable, required: Deal value in minor currency units (cents). No floats.
  - `currency` 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD' | 'JPY' | 'INR', required
  - `stage` Stage, required
    - `id` string, required: Stage id (per-board). Use this in `stageId` / `toStageId` / `stageFilter` write paths.
    - `name` string, required: User-facing stage name. Editable per-board.
    - `region` 'early' | 'anchor' | 'late' | 'won' | 'dead', required: Semantic bucket: early/late are 1..6 user-customizable stages each; anchor is the single per-board "things got serious" milestone; won/dead are immutable terminals.
    - `isAnchor` boolean, required: Convenience flag — `region === "anchor"`.
  - `ownerId` string, uuid, required
  - `ownerName` string, nullable, required
  - `labels` string[], required
  - `primaryContact` object, required
    - `name` string, nullable, required
    - `title` string, nullable, required
    - `email` string, nullable, required
    - `phone` string, nullable, required
    - `linkedin` string, nullable, required
  - `keyTerms` string, nullable, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `stageEnteredAt` string, date-time, required
  - `commitmentAt` string, date-time, nullable, required
  - `wonAt` string, date-time, nullable, required
  - `deadAt` string, date-time, nullable, required

## Other responses

- `400`: Invalid input.
- `401`: Missing or invalid API key.
- `404`: Board not found in your workspace.
- `409`: Idempotency-Key reused with a different body.

---

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