Set Deal Contact Role

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.