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

Unlink a contact from a deal

DELETE /v1/deals/:id/contacts/:relatedId

Unlinks a single contact from a deal; the deal's other contacts stay linked. The contact itself remains in the CRM.

You can restore the link with POST /v1/deals/:id/contacts.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionDeal ID. List: GET /v1/deals
ParameterrelatedId (path) Typenumber Requiredyes DescriptionID of the linked contact — the contactId value from GET /v1/deals/:id/contacts

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/deals/8785/contacts/2921" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

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

JavaScript — OAuth application

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

if (res.status === 204) {
  console.log('Contact 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 by the body.

Response example

HTTP/1.1 204 No Content

Error response example

404 — the contact is not linked to this deal:

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 contact with this ID is linked to this deal — for example, it has already been unlinked. Message: Binding not found
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo deal 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 read-only. 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 contact. If you unlink the primary contact, the first remaining contact in sort order becomes primary. The ID of the new primary contact then arrives in the deal's contactId field.
  • Retry after a lost response. Unlinking the same contact again returns 404 with the message Binding not found: the link no longer exists. To check the result, use the deal contact list.

See also