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

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 arrives in the contact's companyId field. Linking and replacing make the company primary for every contact passed. The IDs of all linked contacts arrive 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

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

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

Examples

curl — personal key

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

curl — OAuth application

Terminal 
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

javascript 
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

javascript 
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

Field Type Description
success boolean Always true on success
data array The company's links to contacts in sort order. An empty array for a company without contacts
data[].contactId number Contact ID. Get the contact: GET /v1/contacts/:id
data[].isPrimary boolean The company is primary for this contact: its ID arrives in the contact's companyId field
data[].sort number The contact's position in the list
data[].roleId number The contact's role in the company. The link methods do not save it

Response example

JSON 
{
  "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:

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

Errors

HTTP Code Description
400 INVALID_PARAMS id is not a positive integer, for example abc
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
403 SCOPE_DENIED The key has no 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 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 arrive in the company's contactIds field.

See also