Create a Deal

POST /deals

Create Deal

cURL

curl --request POST \
  --url https://api.example.com/deals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "account_id": "<string>",
  "value": 123,
  "stage_id": "<string>",
  "close_date": "<string>",
  "currency": "USD",
  "source": "<string>",
  "champion_id": "<string>",
  "notes": "<string>",
  "parent_deal_id": "<string>",
  "competitors": [
    "<string>"
  ]
}
'

422

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

The deal’s owner_id is always the calling user (token.sub) — there’s no way to set a different owner at creation via this endpoint.

Omit stage_id and the deal is created with no stage (stage_id: null) — there’s no fallback to the org’s first stage. An unstaged deal still shows up in List Deals, but not in any column of the board, which is assembled per stage. Pass stage_id, or set it later with Update a Deal.

Five body fields are accepted but not persisted by this endpoint — the handler forwards only name, account_id, value, stage_id, close_date, currency, geo_scope and the owner, so the rest are silently dropped:

Field	How to set it instead
source	Update a Deal
champion_id	Update a Deal
notes	Update a Deal
competitors	Detect Competitors
parent_deal_id	No API path today — PATCH /deals/{deal_id} doesn’t accept it either.

Auth

Requires a CRM manage scope and an active organization on the token. Any *:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.

Side effects

• Emits a deal_created notification event (best-effort, via the org’s Temporal actor workflow).
• Records a deal_created product-analytics event.

Response

201 with {"id": "<new deal id>"} — not the full deal row. Call Get a Deal to fetch it.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name · string · required

Deal name.

Minimum string length: 1

account_id · string | null

Account (company) to link the deal to.

value · number | null

Deal value in currency.

stage_id · string | null

Initial pipeline stage. Omit it and the deal is created with no stage (stage_id: null) — there is no fallback to the org's first stage — so it won't appear in any board column until a stage is set.

close_date · string | null

Expected close date, YYYY-MM-DD.

currency · string · default: USD

ISO 4217 currency code for value.

source · string | null

Free-text origin of the deal (e.g. inbound, referral). Accepted but not persisted by this endpoint — the create handler never passes it through; set it with PATCH /deals/{deal_id} after creating the deal.

champion_id · string | null

Contact id of the internal champion. Accepted but not persisted by this endpoint — the create handler never passes it through; set it with PATCH /deals/{deal_id} after creating the deal.

notes · string | null

Free-text notes. Accepted but not persisted by this endpoint — the create handler never passes it through; set it with PATCH /deals/{deal_id} after creating the deal.

parent_deal_id · string | null

Parent deal id, for renewal/expansion deals linked to a prior one. Accepted but not persisted by this endpoint — the create handler never passes it through, and PATCH /deals/{deal_id} does not accept it either, so there is currently no way to set it through the API.

competitors · string[] | null

Accepted but not persisted by this endpoint — the create handler never passes it through; use POST /deals/{deal_id}/competitors/detect instead.

geo_scope · enum<string> | null

Deal's geographic scope.

Available options: local, regional, international

Response

201

application/json

Successful Response