For AI agents: markdown of this page — /docs-content-en/entities/activities/bindings/bind.md documentation index — /llms.txt

Bind

POST /v1/activities/:activityId/bindings

Binds an activity to an additional CRM entity — it appears in that entity's timeline alongside the owner entity.

Parameters

Parameter Type Required Description
ParameteractivityId (path) Typenumber Requiredyes DescriptionActivity ID. List: GET /v1/activities

Request fields (body)

Field Type Required Description
FieldentityTypeId Typenumber Requiredyes DescriptionNumeric CRM entity-type code:
1 — lead
2 — deal
3 — contact
4 — company
7 — quote
31 — invoice
≥128 — smart-process, its code — in GET /v1/smart-processes
FieldentityId Typenumber Requiredyes DescriptionID of the entity to bind to

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/activities/3631/bindings \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entityTypeId": 3, "entityId": 9 }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/activities/3631/bindings \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "entityTypeId": 3, "entityId": 9 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/activities/3631/bindings', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ entityTypeId: 3, entityId: 9 }),
})

const { data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/activities/3631/bindings', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ entityTypeId: 3, entityId: 9 }),
})

const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.activityId Typenumber DescriptionActivity ID
Fielddata.entityTypeId Typenumber DescriptionNumeric type code of the bound entity
Fielddata.entityId Typenumber DescriptionID of the bound entity
Fielddata.bound Typeboolean Descriptiontrue only if Bitrix24 returned the boolean value true. Otherwise false

Response example

JSON 
{
  "success": true,
  "data": {
    "activityId": 3631,
    "entityTypeId": 3,
    "entityId": 9,
    "bound": true
  }
}

Error response example

422 — the entity is already bound:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Activity is already bound to this entity"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionactivityId, entityTypeId or entityId is not a positive integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo activity exists for the given activityId
HTTP422 CodeBITRIX_ERROR DescriptionThe activity is already bound to this entityTypeId + entityId pair, or no such entity exists
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key's access mode blocks binding changes
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Binding is not idempotent. A repeated request for an already-bound pair returns 422, not 200. It means "already bound", not a failure — there is no need to retry, and no duplicate is added to the list.

See also