> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anycrm.anyreach.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a Deal

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](/api-reference/deals/create-deal); no endpoint on this router reassigns it.

### Auth

Requires a CRM manage [scope](/authentication#scopes) 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](/api-reference/deals/get-deal#the-deal-object), but raw columns only (no `account`/`stage` embeds); use [Get a Deal](/api-reference/deals/get-deal) for the enriched shape.

### Errors

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


## OpenAPI

````yaml PATCH /deals/{deal_id}
openapi: 3.1.0
info:
  title: anycrm-api
  version: 0.0.1
servers: []
security: []
tags:
  - name: Customer Intelligence
    description: >-
      Company research and ICP-fit scoring — create a research run, track its
      progress, and read back scored companies as leads.
  - name: Outreach
    description: >-
      The cold-email management console — domains, mailboxes, and campaigns — as
      a thin control plane over the SalesForge stack.
  - name: AnyCard
    description: >-
      Authenticated CRUD for AnyCard, the org's digital business-card /
      lead-capture product.
  - name: AnyCard Events
    description: >-
      Event-attribution analytics for AnyCard — which captured leads converted,
      broken down by source, owner, and deal.
  - name: AnyCard Share Links
    description: >-
      Unauthenticated endpoints reached by anyone who scans a QR code or opens a
      shared AnyCard link.
  - name: AI
    description: >-
      A streaming (SSE) AI chat endpoint with account-commit actions it can take
      on the caller's behalf.
  - name: Analytics Assistant
    description: >-
      The natural-language analytics assistant — a guarded text-to-SQL loop
      (SSE) that answers ad-hoc questions over the org's CRM data as a
      least-privilege, read-only database role.
  - name: Account Readiness
    description: >-
      Account Readiness Profiles — AI-scored signals on whether an account is
      ready for outreach or expansion, computed via a Temporal workflow.
  - name: Integrations
    description: >-
      Pipedream Connect — issuing connect tokens and managing the org's
      connected third-party accounts.
  - name: Feedback
    description: >-
      User-submitted platform feedback (bug reports, feature requests) — global,
      not scoped to one organization.
  - name: Public Media
    description: >-
      Unauthenticated image reads for publicly-embeddable assets (card photos,
      inline email images) — allowlisted by key shape; everything else in the
      storage bucket stays private.
  - name: Service Health
    description: Service liveness.
paths:
  /deals/{deal_id}:
    patch:
      tags:
        - Deals
      summary: Update Deal
      operationId: update_deal_deals__deal_id__patch
      parameters:
        - name: deal_id
          in: path
          required: true
          schema:
            type: string
            description: The deal's id.
            title: Deal Id
          description: The deal's id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealPatchBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    DealPatchBody:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: New deal name.
        value:
          anyOf:
            - type: number
            - type: 'null'
          title: Value
          description: New deal value; explicit `null` clears it.
        stage_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Stage Id
          description: Move the deal to this pipeline stage.
        close_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Close Date
          description: New expected close date, `YYYY-MM-DD`; explicit `null` clears it.
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
          description: ISO 4217 currency code.
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
          description: Free-text origin of the deal.
        champion_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Champion Id
          description: Contact id of the internal champion.
        notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Notes
          description: Free-text notes.
        win_probability:
          anyOf:
            - type: integer
            - type: 'null'
          title: Win Probability
          description: Manual win-probability override, 0-100.
        close_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Close Reason
          description: Reason code recorded when closing the deal.
        close_notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Close Notes
          description: Free-text notes recorded when closing the deal.
        actual_close:
          anyOf:
            - type: string
            - type: 'null'
          title: Actual Close
          description: Actual close date, `YYYY-MM-DD`.
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
          description: Replace the deal's tag list.
        geo_scope:
          anyOf:
            - type: string
              enum:
                - local
                - regional
                - international
            - type: 'null'
          title: Geo Scope
          description: Deal's geographic scope; explicit `null` clears it.
        stage_change_method:
          anyOf:
            - type: string
              enum:
                - kanban_drag
                - detail_dropdown
                - stage_bar
                - ai_assistant
                - api
            - type: 'null'
          title: Stage Change Method
          description: >-
            Analytics-only hint for how the stage was changed; never persisted
            as a deal column.
      type: object
      title: DealPatchBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````