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

Unlink a company from a contact

DELETE /v1/contacts/:id/companies/:relatedId

Unlinks one company from a contact; the contact's other companies stay linked. The company itself stays in the CRM.

You can restore the binding with POST /v1/contacts/:id/companies by passing the previous sort and isPrimary.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionContact ID. List: GET /v1/contacts
ParameterrelatedId (path) Typenumber Requiredyes DescriptionID of the linked company — the companyId value from GET /v1/contacts/:id/companies

Examples

curl — personal key

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

curl — OAuth application

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

if (res.status === 204) {
  console.log('Company unlinked')
}

JavaScript — OAuth application

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

if (res.status === 204) {
  console.log('Company unlinked')
}

Response

On successful unlinking, the API returns HTTP status 204 No Content with an empty body. Success is indicated by the status code, not the content.

Response example

HTTP/1.1 204 No Content

Error response example

404 — the company is not linked to this contact:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionid or relatedId is not a positive integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo company with this ID is linked to this contact — for example, it has already been unlinked. Message: Binding not found
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no contact with this id. Message: Not found.
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. Unlinking 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

  • Unlinking the primary company. If you unlink the primary company, the first of the remaining companies in sort order becomes primary. The contact field companyId then holds the ID of the new primary company.
  • Retry after a lost response. A 404 with the message Binding not found on a repeated unlink means the binding has already been removed. You can check the result in the list of contact companies.

See also