Company contacts

Links contacts to a company, reads their list, replaces the whole set, and unlinks contacts one at a time or all at once. A link stores the contact's position in the list. Unlinked contacts stay in the CRM.

The isPrimary flag on a link means this company is the contact's primary company: its ID is returned in the contact's companyId field. Linking and replacing make the company primary for every contact passed. The IDs of all linked contacts are returned in the company's contactIds field.

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

List company contacts

GET /v1/companies/:id/contacts

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

Parameters

No pagination: the response contains all of the company's links in one call.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

const { success, data } = await res.json()
const contactIds = data.map((link) => link.contactId)
console.log('Company contacts:', contactIds)

JavaScript — OAuth application

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

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

Response fields

Response example

{
  "success": true,
  "data": [
    { "contactId": 2987, "sort": 10, "isPrimary": true, "roleId": 0 },
    { "contactId": 2989, "sort": 20, "isPrimary": true, "roleId": 0 },
    { "contactId": 2991, "sort": 30, "isPrimary": true, "roleId": 0 }
  ]
}

Error response example

400 — id is not a positive integer:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "id must be a positive integer"
  }
}

Errors

For the full list of common API errors, see Errors.

Known specifics

• A non-existent company returns an empty list. For an ID that does not belong to any company, the method returns 200 with an empty data array, as for a company without contacts. To check that the company exists, use GET /v1/companies/:id: it returns 404 for such an ID.
• An ID from the list may not lead to a contact. Linking does not check the contact ID, so the list can contain an ID that does not belong to any contact. Before working with a contact, request it with GET /v1/contacts/:id.
• Contacts together with the company. GET /v1/companies/:id?include=contact returns the company and the full records of the linked contacts in data._included.contacts. The include value is contact, singular: include=contacts returns 400 INVALID_INCLUDE. The IDs of all linked contacts are returned in the company's contactIds field.

See also

• Company contacts
• Link a contact to a company
• Replace company contacts
• Unlink a contact from a company
• Unlink all contacts from a company
• Get company
• Contacts
• Related data (include)