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

Replace contact companies

PUT /v1/contacts/:id/companies

Defines the contact's entire set of companies in one call: links the companies from the list and unlinks all the others.

To add one company without unlinking the others, use POST /v1/contacts/:id/companies.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionContact ID. List: GET /v1/contacts

Request fields (body)

Field Type Required Description
Fielditems Typearray Requiredyes DescriptionThe contact's new set of companies, including already linked companies that must stay. Companies missing from the array are unlinked. An empty array [] unlinks all companies
Fielditems[].companyId Typenumber Requiredyes DescriptionCompany ID. List: GET /v1/companies. A string of digits is accepted too, for example "3099"
Fielditems[].isPrimary Typeboolean Requiredno DescriptionThe contact's primary company. If no element has true, the first element of the array becomes primary, even if it does not have the lowest sort. If several have true, the first of them becomes primary. To keep the primary company unchanged, pass isPrimary: true for it
Fielditems[].sort Typenumber Requiredno DescriptionThe company's position in the list. If omitted, it is assigned based on the element's position in the array

Examples

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/contacts/2943/companies" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "companyId": 3103, "sort": 10 },
      { "companyId": 3099, "isPrimary": true, "sort": 20 }
    ]
  }'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/contacts/2943/companies" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "companyId": 3103, "sort": 10 },
      { "companyId": 3099, "isPrimary": true, "sort": 20 }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/2943/companies', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      { companyId: 3103, sort: 10 },
      { companyId: 3099, isPrimary: true, sort: 20 },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Companies linked to the contact:', data.length)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/2943/companies', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      { companyId: 3103, sort: 10 },
      { companyId: 3099, isPrimary: true, sort: 20 },
    ],
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionAll of the contact's bindings after the replacement, in sort order. After "items": [] — an empty array
Fielddata[].companyId Typenumber DescriptionCompany ID. Get the company: GET /v1/companies/:id
Fielddata[].isPrimary Typeboolean DescriptionThe contact's primary company. true on exactly one binding
Fielddata[].sort Typenumber DescriptionThe company's position in the list
Fielddata[].roleId Typenumber DescriptionBinding role. The binding methods do not save it

Response example

JSON 
{
  "success": true,
  "data": [
    { "companyId": 3103, "sort": 10, "isPrimary": false, "roleId": 0 },
    { "companyId": 3099, "sort": 20, "isPrimary": true, "roleId": 0 }
  ]
}

Error response example

400 — the body has no items array:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "items must be an array (use [] to unlink all)"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer
HTTP400 CodeINVALID_PARAMS Descriptionitems is not passed or is not an array
HTTP400 CodeINVALID_PARAMS DescriptionAn items element is not an object. The message starts with items[0] must be an object, where 0 is the element's index
HTTP400 CodeINVALID_PARAMS DescriptionAn items element has no companyId, or it cannot be converted to a positive integer, for example 0 or "abc". Message: items[0] requires 'companyId', where 0 is the element's index
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no contact with this id
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 tokens are attached to the key
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode. Replacing requires a key with write access
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded. Retry after the delay in the Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable. Retry the request later

Full list of common API errors — Errors.

Known specifics

  • Company existence is not checked. An ID that does not belong to any company is linked without an error and appears in the contact's list of bindings. Before replacing, check the companies with GET /v1/companies/:id.
  • The role is not saved. The roleId field in an items element is accepted without an error but is not saved: in the response, roleId is 0.

See also