Update Deal

PATCH

/deals/{deal_id}

Production
QA

Update a deal (partial update).

Contact operations run in a fixed order within the single transaction: remove_contact_ids -> add_contact_ids -> contact_roles. That order is what makes the useful combinations work:

a contact linked by add_contact_ids in THIS request can be given a role by contact_roles in the same call (roles run last);
an id in both remove_contact_ids and add_contact_ids ends up linked (add runs after remove), so a role for it still applies;
an id in remove_contact_ids and contact_roles but NOT in add_contact_ids is unlinked by the time roles run, so it is a 422 naming that id rather than a role written to a row that no longer exists.

A contact_roles entry for a contact that is neither already linked nor being added is a 422; the whole transaction rolls back, so a partially applied batch is not a state this endpoint can produce.

background_tasks carries the deal.stage_changed fan-out only. It is injected, not a body field, so it does not appear in the OpenAPI schema and the request contract is unchanged (pinned by developer_api/tests/test_deal_stage_events.py). Publishing there rather than inline keeps the Redis round trip off the caller’s latency budget and makes “strictly after the commit” structural: the task is queued only after the session context has exited, and FastAPI attaches background tasks to the SUCCESS response, so a raise anywhere above publishes nothing.

Authorizations

BearerAuth

Parameters

Path Parameters

deal_id

required

Deal ID (UUID)

string

Deal ID (UUID)

Header Parameters

X-Target-Org-Id

Any of:

string
null

string

Request Body^required

object

add_contact_ids

Mashup_contact_ids to add to the deal (must match the deal’s company; idempotent)

Array<integer>

amount

Any of:

number
null

number

close_date

Any of:

string
null

string

contact_roles

Any of:

object
null

object

key

additional properties

Any of:

string
null

string

currency

Any of:

string
null

string

description

Any of:

string
null

string

expected_revision

Any of:

integer
null

integer

>= 1

name

Any of:

string
null

string

owner_id

Any of:

string
null

string

remove_contact_ids

Mashup_contact_ids to remove from the deal (idempotent — unlinked skipped)

Array<integer>

stage_id

Any of:

string
null

string

Responses

200

Successful Response

object

data

required

object

amount

Any of:

number
null

number

close_date

Any of:

string
null

string

closed_lost_reason

Any of:

string
null

string

company_id

Any of:

unknown
null

contact_count

integer

contacts

Any of:

Array<object>
null

Array<object>

Lightweight contact summary embedded in deal responses.

id is the canonical mashup_contact_id (BigInt), matching how contacts are addressed everywhere else in the public API (g8_search_contacts, g8_lookup_person, etc.). role is the contact’s role within THIS deal (champion / decision_maker / influencer / blocker / coach / end_user) and is null when no role was set.

object

email

Any of: