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

List contact companies

GET /v1/contacts/:id/companies

Returns all companies linked to a contact, so you know the current set before linking, replacing, or unlinking.

Parameters

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

There is no pagination: the response contains all of the contact's bindings in one call.

Examples

curl — personal key

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

curl — OAuth application

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

const { success, data } = await res.json()
const primary = data.find((link) => link.isPrimary)
console.log('Primary company:', primary?.companyId)

JavaScript — OAuth application

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

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionThe contact's company bindings in sort order. For a contact without companies — an empty array
Fielddata[].companyId Typenumber DescriptionCompany ID. Get the company: GET /v1/companies/:id
Fielddata[].isPrimary Typeboolean DescriptionThe contact's primary company. For a contact with companies, true on exactly one binding
Fielddata[].sort Typenumber DescriptionThe company's position in the list
Fielddata[].roleId Typenumber DescriptionBinding role. The binding methods do not save it

Response example

JSON 
{
  "success": true,
  "data": [
    { "companyId": 3099, "sort": 10, "isPrimary": false, "roleId": 0 },
    { "companyId": 3101, "sort": 20, "isPrimary": true, "roleId": 0 },
    { "companyId": 3103, "sort": 30, "isPrimary": false, "roleId": 0 }
  ]
}

Error response example

400 — id in the path is not a positive integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "id must be a positive integer"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer, for example abc
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
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable. Retry the request later

For the full list of common API errors, see Errors.

Known specifics

  • An empty list is also returned for a nonexistent contact. For an ID that does not belong to any contact, the method returns 200 with an empty data, as for a contact without companies. To tell these cases apart, request the contact with GET /v1/contacts/:id: for a nonexistent contact it returns 404 ENTITY_NOT_FOUND.
  • An ID in the list might not point to an existing company. Linking does not check the company ID, so the list can contain an ID that does not belong to any company. Before working with a company, request it with GET /v1/companies/:id.
  • Companies together with the contact. GET /v1/contacts/:id?include=companyBinding returns the contact and the full records of all linked companies in data._included.companyBindings; with include=company, only the primary company in data._included.company. The primary company's ID is returned in the contact's companyId field, and the IDs of all linked companies are returned in companyIds.

See also