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
activityId (path) number yes Activity ID. List: GET /v1/activities

Request fields (body)

Field Type Required Description
entityTypeId number yes Numeric 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
entityId number yes ID 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 app

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 app

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
success boolean Always true on success
data.activityId number Activity ID
data.entityTypeId number Numeric type code of the bound entity
data.entityId number ID of the bound entity
data.bound boolean Always true — confirmation of the binding

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
400 INVALID_PARAMS activityId, entityTypeId or entityId is not a positive integer
404 ENTITY_NOT_FOUND No activity exists for the given activityId
422 BITRIX_ERROR The activity is already bound to this entityTypeId + entityId pair, or no such entity exists
403 SCOPE_DENIED The key lacks the crm scope
401 TOKEN_MISSING The 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