Contact companies

Links companies to a contact, replaces the whole set, reads the list, and unlinks companies one at a time or all at once. A binding stores the company's position in the list and the primary-company flag. Unlinked companies stay in the CRM.

A contact with companies always has one primary company. Its ID arrives in the contact's companyId field, and the IDs of all linked companies arrive in the companyIds field in sort order. The companyIds field is writable: PATCH /v1/contacts/:id with it replaces the whole set of companies, the same way as PUT /v1/contacts/:id/companies. Companies missing from the array are unlinked.

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

List contact companies

GET /v1/contacts/:id/companies

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

Parameters

There is no pagination: the response contains all of the contact's bindings in one call.

Examples

curl — personal key

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

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/contacts/2943/companies" \
  -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/contacts/2943/companies', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/2943/companies', {
  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": [
    { "companyId": 3099, "sort": 10, "isPrimary": false, "roleId": 0 },
    { "companyId": 3101, "sort": 20, "isPrimary": true, "roleId": 0 },
    { "companyId": 3103, "sort": 30, "isPrimary": false, "roleId": 0 }
  ]
}

Error response example

400 — id in the path is not a positive integer:

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

Errors

Full list of common API errors — Errors.

Known specifics

• An empty list for a nonexistent contact too. For an ID that does not belong to any contact, the method returns 200 with an empty data, as for a contact without companies. To tell these cases apart, request the contact with GET /v1/contacts/:id: for a nonexistent contact it returns 404 ENTITY_NOT_FOUND.
• An ID in the list might not point to an existing company. Linking does not check the company ID, so the list can contain an ID that does not belong to any company. Before working with a company, request it with GET /v1/companies/:id.
• Companies together with the contact. GET /v1/contacts/:id?include=companyBinding returns the contact and the full records of all linked companies in data._included.companyBindings; with include=company, only the primary company in data._included.company. The primary company's ID arrives in the contact field companyId, and the IDs of all linked companies in companyIds.

See also

• Contact companies
• Link a company to a contact
• Replace contact companies
• Unlink a company from a contact
• Unlink all companies from a contact
• Get contact
• Companies