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

Replace lead contacts

PUT /v1/leads/:id/contacts

Replaces the whole set of lead contacts in one call: links the contacts from the list and unlinks all others.

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

Parameters

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

Request fields (body)

Field Type Required Description
Fielditems Typearray Requiredyes DescriptionThe new set of lead contacts, including already linked contacts that must stay. Contacts missing from the array are unlinked. An empty array [] unlinks all contacts
Fielditems[].contactId Typenumber Requiredyes DescriptionContact ID. List: GET /v1/contacts
Fielditems[].isPrimary Typeboolean Requiredno DescriptionPrimary contact of the lead. If no element has true, the first array element becomes primary. If several elements have true, the first of them does
Fielditems[].sort Typenumber Requiredno DescriptionPosition of the contact in the list. If omitted, it is set by the element's position: 10 for the first, 20 for the second

Examples

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/leads/1001321/contacts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "contactId": 2941, "sort": 10 },
      { "contactId": 2937, "isPrimary": true, "sort": 20 }
    ]
  }'

curl — OAuth application

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

JavaScript — personal key

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

const { success, data } = await res.json()
console.log('Lead contacts:', data.length)

JavaScript — OAuth application

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

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionAll links of the lead after the replacement, in sort order. An empty array after "items": []
Fielddata[].contactId Typenumber DescriptionContact ID. Get the contact: GET /v1/contacts/:id
Fielddata[].isPrimary Typeboolean DescriptionPrimary contact of the lead. true on exactly one link
Fielddata[].sort Typenumber DescriptionPosition of the contact in the list
Fielddata[].roleId Typenumber DescriptionRole of the contact in the lead. The link methods do not store it

Response example

JSON 
{
  "success": true,
  "data": [
    { "contactId": 2941, "sort": 10, "isPrimary": false, "roleId": 0 },
    { "contactId": 2937, "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 missing or is not an array
HTTP400 CodeINVALID_PARAMS DescriptionAn items element is not an object. The message starts with the element index: items[0] must be an object
HTTP400 CodeINVALID_PARAMS DescriptionAn items element has no contactId, or contactId is not a positive integer. The message names the element index: items[0] requires 'contactId'
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo lead with this id exists
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. Replacement 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

  • Contact existence is not checked. An ID that matches no contact is linked without an error and appears in the lead's list of links. Before the replacement, check the contacts with GET /v1/contacts/:id.
  • The role is not stored. The roleId field in an items element is accepted without an error but is not stored: in the response, the new link has roleId equal to 0.

See also