Update a Deal

PATCH /deals/{deal_id}

Update Deal

cURL

curl --request PATCH \
  --url https://api.example.com/deals/{deal_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "value": 123,
  "stage_id": "<string>",
  "close_date": "<string>",
  "currency": "<string>",
  "source": "<string>",
  "champion_id": "<string>",
  "notes": "<string>",
  "win_probability": 123,
  "close_reason": "<string>",
  "close_notes": "<string>",
  "actual_close": "<string>",
  "tags": [
    "<string>"
  ]
}
'

422

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

Runs through the same shared update service used everywhere else a deal can be mutated, so every caller gets identical side effects.

value, close_date, and geo_scope are special: sending an explicit null clears the column and still counts as a change; for every other field, sending null is treated the same as omitting it (no-op).

Owner reassignment isn’t possible here. owner_id is not a field on this endpoint’s body, so it’s dropped before validation — a request whose only key is owner_id reaches the handler with nothing to update and returns 400. A deal’s owner is fixed to its creator at creation; no endpoint on this router reassigns it.

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

• If stage_id changes: dispatches a DealUpdateWorkflow (Temporal) that logs the stage-change activity and evaluates AI next-actions/contact-promotion off the request path, and records a stage_change analytics event.
• Classifies and enqueues notification events for changes to stage_id, value, or close_date. (owner_id is also a notifiable field, but it isn’t part of this endpoint’s body — see above.)

Response

The updated deals row — same fields as the deal object, but raw columns only (no account/stage embeds); use Get a Deal for the enriched shape.

Errors

Status	Cause
400	Body has no fields to update.
404	No deal with that id in this org.

Authorizations

Authorization · string · header · required

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

Path Parameters

deal_id · string · required

The deal's id.

Body

application/json

name · string | null

New deal name.

value · number | null

New deal value; explicit null clears it.

stage_id · string | null

Move the deal to this pipeline stage.

close_date · string | null

New expected close date, YYYY-MM-DD; explicit null clears it.

currency · string | null

ISO 4217 currency code.

source · string | null

Free-text origin of the deal.

champion_id · string | null

Contact id of the internal champion.

notes · string | null

Free-text notes.

win_probability · integer | null

Manual win-probability override, 0-100.

close_reason · string | null

Reason code recorded when closing the deal.

close_notes · string | null

Free-text notes recorded when closing the deal.

actual_close · string | null

Actual close date, YYYY-MM-DD.

tags · string[] | null

Replace the deal's tag list.

geo_scope · enum<string> | null

Deal's geographic scope; explicit null clears it.

Available options: local, regional, international

stage_change_method · enum<string> | null

Analytics-only hint for how the stage was changed; never persisted as a deal column.

Available options: kanban_drag, detail_dropdown, stage_bar, ai_assistant, api

Response

200

application/json

Successful Response