#Deal contacts

Manage the deal-to-contacts links (many-to-many). The contactIds field on the deal itself is read-only — PATCH /v1/deals/:id does not change it. To link, replace, or unlink contacts, use the endpoints below. To read the contacts together with the deal, use GET /v1/deals/:id?include=contact (see "Including related entities").

Requires the crm scope.

#Link fields

#Get deal contacts

GET /v1/deals/:id/contacts

Returns the array of linked contacts.

curl "https://vibecode.bitrix24.com/v1/deals/741/contacts" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "data": [
    { "contactId": 9, "sort": 10, "isPrimary": true, "roleId": 0 },
    { "contactId": 17, "sort": 20, "isPrimary": false, "roleId": 0 }
  ]
}

#Add a single contact

POST /v1/deals/:id/contacts

Links one contact to the deal without touching the already-linked ones.

curl -X POST "https://vibecode.bitrix24.com/v1/deals/741/contacts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": 9, "isPrimary": true, "sort": 10 }'

Returns the updated deal contact list (as in GET).

#Replace the whole contact list

PUT /v1/deals/:id/contacts

Fully replaces the deal contact list. Contacts not present in items are unlinked. Pass "items": [] to unlink all.

curl -X PUT "https://vibecode.bitrix24.com/v1/deals/741/contacts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "contactId": 16530, "isPrimary": true, "sort": 10 },
      { "contactId": 16532, "isPrimary": false, "sort": 20 }
    ]
  }'

Returns the updated deal contact list (as in GET).

#Delete a single contact

DELETE /v1/deals/:id/contacts/:contactId

Unlinks one contact. If the primary one is removed, the first remaining becomes primary.

curl -X DELETE "https://vibecode.bitrix24.com/v1/deals/741/contacts/16530" \
  -H "X-Api-Key: YOUR_API_KEY"

Returns 204 No Content.

#Errors