For AI agents: markdown of this page — /docs-content-en/entities/deals/contacts.md documentation index — /llms.txt

Deal contacts

Links contacts to a deal, reads the list of linked contacts, and unlinks them one at a time or all at once. A link stores the contact's position in the list and the primary-contact flag. Unlinking leaves the contacts themselves in the CRM.

A deal with contacts always has exactly one primary contact. Its ID arrives in the deal's contactId field, and the IDs of all linked contacts arrive in the contactIds field. The contactIds field is read-only: PATCH /v1/deals/:id with it returns 400 READONLY_FIELD, so change the set of contacts with the methods below.

Bitrix24 API: crm.deal.contact.items.get, crm.deal.contact.add, crm.deal.contact.items.set, crm.deal.contact.delete, crm.deal.contact.items.delete Scope: crm

List deal contacts

GET /v1/deals/:id/contacts

Returns all contacts linked to a deal, so that you know the current set before linking, replacing, or unlinking contacts.

Parameters

Parameter Type Required Description
id (path) number yes Deal ID. List: GET /v1/deals

There is no pagination: one call returns all of the deal's links.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/deals/8785/contacts" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deals/8785/contacts', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
const primary = data.find((link) => link.isPrimary)
console.log('Primary contact:', primary?.contactId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deals/8785/contacts', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Links between the deal and its contacts, ordered by sort. An empty array for a deal without contacts
data[].contactId number Contact ID. Get the contact: GET /v1/contacts/:id
data[].isPrimary boolean Primary contact of the deal. For a deal with contacts, exactly one link has true
data[].sort number Position of the contact in the list
data[].roleId number Role of the contact in the deal. The link methods do not save it

Response example

JSON 
{
  "success": true,
  "data": [
    { "contactId": 2921, "sort": 10, "isPrimary": false, "roleId": 0 },
    { "contactId": 2923, "sort": 20, "isPrimary": true, "roleId": 0 },
    { "contactId": 2925, "sort": 30, "isPrimary": false, "roleId": 0 }
  ]
}

Error response example

404 — no deal with this id:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Not found"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS id is not a positive integer, for example abc
404 ENTITY_NOT_FOUND No deal with this id
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING No Bitrix24 tokens are attached to the key
403 SCOPE_DENIED The key lacks the crm scope
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable. Retry the request later

Full list of common API errors — Errors.

Known specifics

  • A listed ID may not lead to a contact. Linking does not check the contact ID, so the list can contain an ID that matches no contact. Before working with a contact, request it through GET /v1/contacts/:id.
  • Contacts together with the deal. GET /v1/deals/:id?include=contact returns the deal and the full records of the linked contacts in data._included.contacts. The ID of the primary contact arrives in the deal's contactId field, and the IDs of all linked contacts in contactIds.

See also