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

Link a contact to a company

POST /v1/companies/:id/contacts

Links one contact to a company; the company's other contacts stay linked.

To set the full list of contacts in one call, use PUT /v1/companies/:id/contacts.

Parameters

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

Request fields (body)

Field Type Required Description
FieldcontactId Typenumber Requiredyes DescriptionContact ID. List: GET /v1/contacts. A string of digits is also accepted, for example "2989"
FieldisPrimary Typeboolean Requiredno DescriptionIgnored: linking always makes the company primary for the contact, and the new link has isPrimary: true in the response
Fieldsort Typenumber Requiredno DescriptionThe contact's position in the list. If omitted, the link is added to the end of the list

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/companies/3123/contacts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": 2989, "sort": 20 }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/companies/3123/contacts" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": 2989, "sort": 20 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/companies/3123/contacts', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ contactId: 2989, sort: 20 }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/companies/3123/contacts', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ contactId: 2989, sort: 20 }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionAll of the company's links after linking, in sort order
Fielddata[].contactId Typenumber DescriptionContact ID. Get the contact: GET /v1/contacts/:id
Fielddata[].isPrimary Typeboolean DescriptionThe company is primary for this contact: its ID arrives in the contact's companyId field
Fielddata[].sort Typenumber DescriptionThe contact's position in the list
Fielddata[].roleId Typenumber DescriptionThe contact's role in the company. The link methods do not save it

Response example

A second contact is linked to a company that has one contact:

JSON 
{
  "success": true,
  "data": [
    { "contactId": 2987, "sort": 10, "isPrimary": true, "roleId": 0 },
    { "contactId": 2989, "sort": 20, "isPrimary": true, "roleId": 0 }
  ]
}

Error response example

409 — the contact is already linked to this company:

JSON 
{
  "success": false,
  "error": {
    "code": "RELATION_ALREADY_EXISTS",
    "message": "This binding already exists"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptioncontactId is missing or is not a positive integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo company with this id
HTTP409 CodeRELATION_ALREADY_EXISTS DescriptionThe contact is already linked to this company
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP403 CodeSCOPE_DENIED DescriptionThe key has no crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode. Linking 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

  • The company becomes the contact's primary company. After linking, the contact's companyId field contains the ID of this company, and the contact's link to its previous primary company gets isPrimary: false.
  • Contact existence is not checked. An ID that does not belong to any contact is linked without an error and appears in the company's list of links. Before linking, check the contact with GET /v1/contacts/:id.
  • The role is not saved. The roleId field in the body is accepted without an error but is not saved: the new link has roleId equal to 0 in the response.
  • Position of an already linked contact. Linking the same contact again answers 409. To change the position of contacts that are already linked, use PUT /v1/companies/:id/contacts and pass the full desired set of contacts in items: contacts missing from items are unlinked.

See also