Set Deal Contact Role
PUT /deals/{deal_id}/contacts/{contact_id}
Set (or clear) a contact’s buying-committee role on a deal.
The role lives on the deal-contact LINK (cb_deal_contacts.role), not on
the contact: the same person can be a champion on one deal and an end user
on another. This endpoint only re-roles an EXISTING link — it never
creates one, so attaching and roling stay separately auditable. Use
PATCH /deals/{deal_id} with add_contact_ids (optionally alongside
contact_roles) to link a contact first.
{contact_id} is the mashup_contact_id, the same integer id this API
uses for a contact everywhere else (GET /contacts/{id}, the id on
every ContactBrief). The internal app route calls the identical value
{person_id}; that name is a historical misnomer and is not repeated
here.
Body is {"role": "champion"}; an explicit {"role": null} clears the
role. role is required — an empty body is a 422, because a PUT that
names no new state for the sub-resource is a caller bug, and reading
omission as “clear” would destroy data on a typo.
Returns the updated contact. 404 when the deal does not exist in this org or the contact is not linked to it; 422 on a role outside the vocabulary.
Authorizations
Parameters
Path Parameters
Deal ID (UUID)
Deal ID (UUID)
Mashup_contact_id (BigInt) of a contact already linked to this deal
Mashup_contact_id (BigInt) of a contact already linked to this deal
Header Parameters
Request Body required
Body for PUT /deals/{deal_id}/contacts/{contact_id}.
role is REQUIRED but nullable. That combination is the whole point of a
PUT here: {"role": "champion"} sets it, {"role": null} clears it, and
an empty body {} is a 422 rather than a silent no-op — a PUT that says
nothing about the sub-resource it is replacing is a caller bug, and the
alternative (treating omission as “clear”) would delete data on a typo.
Responses
200
Successful Response
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.
422
Validation Error