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

Unlink a contact from a lead

DELETE /v1/leads/:id/contacts/:relatedId

Unlinks one contact from a lead. The lead's other contacts stay linked. The contact itself stays in the CRM.

You can restore the link with POST /v1/leads/:id/contacts. To put the contact back in its previous position and make it primary again, pass its previous sort and isPrimary.

Parameters

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

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/leads/1001321/contacts/2937" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/leads/1001321/contacts/2937" \
  -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/leads/1001321/contacts/2937', {
  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/leads/1001321/contacts/2937', {
  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 content.

Response example

HTTP/1.1 204 No Content

Error response example

404 — the contact is not linked to this lead:

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 lead, for example because it has already been unlinked. The message is Binding not found
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo lead with this id exists. The message is Not found.
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens attached
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have 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 contact. If you unlink the primary contact, the first of the remaining contacts in sort order becomes primary. Its ID arrives in the contactId field of the GET /v1/leads/:id response.
  • Retrying after a lost response. Unlinking the same contact again returns 404 with the message Binding not found: the link no longer exists. Check the result in the list of lead contacts.

See also